@openlfcp/wire 0.1.0-rc.1

package/dist/objects.d.ts

@@ -0,0 +1,154 @@
+import { type ActorSequence, type ControlRecordId, type DataEpoch, type DataUnitId, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type CborValue } from "./cbor/index.js";
+import { type SignedObject } from "./cose.js";
+import { type ActorHave } from "./have.js";
+/**
+ * Typed payloads of the persistent LFCP signed objects (LFCP-WIRE-01 §13,
+ * §25, §26, §29), on top of the canonical COSE_Sign1 layer in cose.ts.
+ *
+ * `parseX(bytes)` returns `{ signed, payload }`: `signed` is the
+ * `parseSignedObject` result and `payload` is decoded from
+ * `signed.payloadBytes`. The decoders check structure only: the field set,
+ * field types and byte lengths, and the structural rules named on each
+ * payload. Signer authority, chain linkage, epochs, cutoff frontiers, AEAD
+ * and HPKE belong to LFCP-020 to LFCP-025.
+ *
+ * Exact bytes: hashing and signature verification always use the received
+ * bytes. The object ID is SHA-256 of `signed.bytes` and the signature is
+ * checked over `signed.protectedBytes` and `signed.payloadBytes`, exactly as
+ * received. The N7 rule (§5.2, §10.3: decode, re-encode and compare) is only a
+ * rejection test. Its re-encoding is compared and then thrown away; it never
+ * becomes an object's bytes, and no ID or signature input is ever rebuilt
+ * from a parsed payload.
+ *
+ * Errors and their wire mapping (ADR 0001):
+ * - COSE_MALFORMED, CBOR_* and INVALID_STRUCTURE → MALFORMED_MESSAGE;
+ * - UNSUPPORTED_VALUE (reserved core Control Record type) →
+ *   INVALID_CONTROL_CHAIN (§14);
+ * - INVALID_CONTROL_CHAIN (a Genesis not at control_seq 0 with a null
+ *   link, §13.1) → INVALID_CONTROL_CHAIN;
+ * - a failed `verifySignedObject` against the expected signer → INVALID_SIGNATURE.
+ */
+/** A parsed signed object: the exact received object and its typed payload. */
+export interface Parsed<P> {
+    readonly signed: SignedObject;
+    readonly payload: P;
+}
+/** §14 Control Record types defined by LFCP-WIRE-01. 9–31 are reserved; 32 and up are extensions. */
+export declare const CONTROL_TYPE: Readonly<{
+    GENESIS: 0n;
+    CAPABILITY_GRANT: 1n;
+    CAPABILITY_REVOKE: 2n;
+    CAPABILITY_CLAIM: 3n;
+    KEY_EPOCH: 4n;
+    ROUTE_UPDATE: 5n;
+    OWNER_TRANSFER_COMMIT: 6n;
+    COORDINATOR_RECOVERY: 7n;
+    RESOURCE_TOMBSTONE: 8n;
+}>;
+/**
+ * `control-record-payload` (§13). The body is the decoded `any` value. It is
+ * deterministic CBOR (checked with the payload) but not typed here; typed
+ * bodies are LFCP-019.
+ */
+export interface ControlRecordPayload {
+    readonly kind: "control-record";
+    readonly resourceId: ResourceId;
+    readonly controlSeq: bigint;
+    readonly prevControlId: ControlRecordId | null;
+    readonly controlType: bigint;
+    /** True for extension types (32 and up), which §14 lets a receiver keep without interpreting. */
+    readonly extension: boolean;
+    /**
+     * The payload's issuer field. Whether the issuer may issue this record
+     * (and who must have signed it) is decided by LFCP-019 to LFCP-021.
+     */
+    readonly issuer: PrincipalId;
+    readonly body: CborValue;
+}
+/** `data-unit-payload` (§26). */
+export interface DataUnitPayload {
+    readonly kind: "data-unit";
+    readonly resourceId: ResourceId;
+    readonly dataEpoch: DataEpoch;
+    readonly actor: PrincipalId;
+    readonly actorSeq: ActorSequence;
+    readonly prevDataUnitId: DataUnitId | null;
+    readonly controlHead: ControlRecordId;
+    readonly ciphertext: Uint8Array;
+}
+/** `key-package-payload` (§25). */
+export interface KeyPackagePayload {
+    readonly kind: "key-package";
+    readonly resourceId: ResourceId;
+    readonly dataEpoch: DataEpoch;
+    readonly recipient: PrincipalId;
+    readonly controlHead: ControlRecordId;
+    readonly sender: PrincipalId;
+    readonly hpkeEnc: Uint8Array;
+    readonly hpkeCiphertext: Uint8Array;
+}
+/** `snapshot-payload` (§29). */
+export interface SnapshotPayload {
+    readonly kind: "snapshot";
+    readonly resourceId: ResourceId;
+    readonly dataEpoch: DataEpoch;
+    readonly publisher: PrincipalId;
+    readonly snapshotSeq: bigint;
+    readonly controlHead: ControlRecordId;
+    readonly frontier: readonly ActorHave[];
+    readonly ciphertext: Uint8Array;
+}
+/**
+ * Structural rules: the §13 field set, a §14 type that is not reserved
+ * (UNSUPPORTED_VALUE otherwise), and a Genesis record (type 0) at
+ * control_seq 0 with a null link (§13.1: INVALID_CONTROL_CHAIN otherwise).
+ * Sequence continuity and prev_control_id linkage are chain validation
+ * (LFCP-020).
+ */
+export declare function controlRecordPayloadFromCbor(value: CborValue): ControlRecordPayload;
+/**
+ * Structural rules: the §26 field set and actor sequence >= 1 (§8, N4).
+ * A non-null previous unit at sequence 1 is not rejected here: §26.2 asks
+ * for it to be reported to the sync engine, and the actor_seq1_prev_not_null_D1
+ * vector's disposition is "report", not reject (LFCP-025, LFCP-028).
+ */
+export declare function dataUnitPayloadFromCbor(value: CborValue): DataUnitPayload;
+/**
+ * Structural rules: the §25 field set, with `5 => bstr .size 32` (HPKE
+ * enc) and `6 => bstr .size 48` (the 32-byte DEK and the 16-byte tag).
+ * HPKE and authority checks are key-package.ts.
+ */
+export declare function keyPackagePayloadFromCbor(value: CborValue): KeyPackagePayload;
+/**
+ * Structural rules: the §29 field set, a Snapshot Sequence of at least 1
+ * (§29: "Snapshot Sequences begin at 1"; §29 names no code, so this is
+ * INVALID_STRUCTURE like actor sequence 0) and a canonical frontier
+ * (§28.1, §28.2, N6).
+ */
+export declare function snapshotPayloadFromCbor(value: CborValue): SnapshotPayload;
+/** Decodes standalone payload bytes; they must be deterministic CBOR (N7). */
+export declare const decodeControlRecordPayload: (payloadBytes: Uint8Array) => ControlRecordPayload;
+export declare const decodeDataUnitPayload: (payloadBytes: Uint8Array) => DataUnitPayload;
+export declare const decodeKeyPackagePayload: (payloadBytes: Uint8Array) => KeyPackagePayload;
+export declare const decodeSnapshotPayload: (payloadBytes: Uint8Array) => SnapshotPayload;
+/** Parses a received Control Record (§13) without verifying its signature. */
+export declare const parseControlRecord: (bytes: Uint8Array) => Parsed<ControlRecordPayload>;
+/** Parses a received Data Unit (§26) without verifying its signature. */
+export declare const parseDataUnit: (bytes: Uint8Array) => Parsed<DataUnitPayload>;
+/** Parses a received Key Package (§25) without verifying its signature. */
+export declare const parseKeyPackage: (bytes: Uint8Array) => Parsed<KeyPackagePayload>;
+/** Parses a received Snapshot (§29) without verifying its signature. */
+export declare const parseSnapshot: (bytes: Uint8Array) => Parsed<SnapshotPayload>;
+/**
+ * The Principal that must have signed a data-plane object, read from its
+ * payload: the actor of a Data Unit (§26), the sender of a Key Package
+ * (§25) and the publisher of a Snapshot (§29). The caller resolves this ID to
+ * a Principal Descriptor and passes it to `verifySignedObject`; a `kid` that
+ * names anyone else fails as KID_MISMATCH (INVALID_SIGNATURE, G1/N2).
+ *
+ * Control Records have no hook: who must sign one depends on its type and on
+ * the chain (LFCP-019 to LFCP-021). Their payload's `issuer` is exposed as is.
+ */
+export declare function expectedSignerOf(payload: DataUnitPayload | KeyPackagePayload | SnapshotPayload): PrincipalId;
+//# sourceMappingURL=objects.d.ts.map

package/dist/objects.js

@@ -0,0 +1,156 @@
+import { actorSequence, controlRecordId, dataEpoch, dataUnitId, LfcpError, principalId, resourceId, } from "@openlfcp/core";
+import { decodeDeterministic, decodeStrict } from "./cbor/index.js";
+import { parseSignedObject } from "./cose.js";
+import { Fields, invalid } from "./fields.js";
+import { canonicalFrontierFromCbor } from "./have.js";
+/** §14 Control Record types defined by LFCP-WIRE-01. 9–31 are reserved; 32 and up are extensions. */
+export const CONTROL_TYPE = Object.freeze({
+    GENESIS: 0n,
+    CAPABILITY_GRANT: 1n,
+    CAPABILITY_REVOKE: 2n,
+    CAPABILITY_CLAIM: 3n,
+    KEY_EPOCH: 4n,
+    ROUTE_UPDATE: 5n,
+    OWNER_TRANSFER_COMMIT: 6n,
+    COORDINATOR_RECOVERY: 7n,
+    RESOURCE_TOMBSTONE: 8n,
+});
+const FIRST_RESERVED_CONTROL_TYPE = 9n;
+const FIRST_EXTENSION_CONTROL_TYPE = 32n;
+const ALL_FIELDS = [0, 1, 2, 3, 4, 5, 6];
+/**
+ * Structural rules: the §13 field set, a §14 type that is not reserved
+ * (UNSUPPORTED_VALUE otherwise), and a Genesis record (type 0) at
+ * control_seq 0 with a null link (§13.1: INVALID_CONTROL_CHAIN otherwise).
+ * Sequence continuity and prev_control_id linkage are chain validation
+ * (LFCP-020).
+ */
+export function controlRecordPayloadFromCbor(value) {
+    const f = new Fields(value, "control-record-payload", ALL_FIELDS.slice(0, 6));
+    const rid = resourceId(f.bytes(0, 32));
+    const controlSeq = f.uint(1);
+    const prev = f.bytesOrNull(2, 32);
+    const controlType = f.uint(3);
+    const issuer = principalId(f.bytes(4, 32));
+    if (controlType >= FIRST_RESERVED_CONTROL_TYPE && controlType < FIRST_EXTENSION_CONTROL_TYPE) {
+        throw new LfcpError("UNSUPPORTED_VALUE", `Control Record type ${controlType} is reserved for LFCP core (§14)`);
+    }
+    if (controlType === CONTROL_TYPE.GENESIS && (controlSeq !== 0n || prev !== null))
+        throw new LfcpError("INVALID_CONTROL_CHAIN", "a Genesis record must have control_seq 0 and a null prev_control_id (§13.1)");
+    return Object.freeze({
+        kind: "control-record",
+        resourceId: rid,
+        controlSeq,
+        prevControlId: prev === null ? null : controlRecordId(prev),
+        controlType,
+        extension: controlType >= FIRST_EXTENSION_CONTROL_TYPE,
+        issuer,
+        body: f.any(5),
+    });
+}
+/**
+ * Structural rules: the §26 field set and actor sequence >= 1 (§8, N4).
+ * A non-null previous unit at sequence 1 is not rejected here: §26.2 asks
+ * for it to be reported to the sync engine, and the actor_seq1_prev_not_null_D1
+ * vector's disposition is "report", not reject (LFCP-025, LFCP-028).
+ */
+export function dataUnitPayloadFromCbor(value) {
+    const f = new Fields(value, "data-unit-payload", ALL_FIELDS);
+    const prev = f.bytesOrNull(4, 32);
+    const actorSeq = f.uint(3);
+    if (actorSeq === 0n)
+        f.fail(3, "(actor sequence) must be at least 1 (§8)");
+    return Object.freeze({
+        kind: "data-unit",
+        resourceId: resourceId(f.bytes(0, 32)),
+        dataEpoch: dataEpoch(f.uint(1)),
+        actor: principalId(f.bytes(2, 32)),
+        actorSeq: actorSequence(actorSeq),
+        prevDataUnitId: prev === null ? null : dataUnitId(prev),
+        controlHead: controlRecordId(f.bytes(5, 32)),
+        ciphertext: f.bytes(6),
+    });
+}
+/**
+ * Structural rules: the §25 field set, with `5 => bstr .size 32` (HPKE
+ * enc) and `6 => bstr .size 48` (the 32-byte DEK and the 16-byte tag).
+ * HPKE and authority checks are key-package.ts.
+ */
+export function keyPackagePayloadFromCbor(value) {
+    const f = new Fields(value, "key-package-payload", ALL_FIELDS);
+    return Object.freeze({
+        kind: "key-package",
+        resourceId: resourceId(f.bytes(0, 32)),
+        dataEpoch: dataEpoch(f.uint(1)),
+        recipient: principalId(f.bytes(2, 32)),
+        controlHead: controlRecordId(f.bytes(3, 32)),
+        sender: principalId(f.bytes(4, 32)),
+        hpkeEnc: f.bytes(5, 32),
+        hpkeCiphertext: f.bytes(6, 48),
+    });
+}
+/**
+ * Structural rules: the §29 field set, a Snapshot Sequence of at least 1
+ * (§29: "Snapshot Sequences begin at 1"; §29 names no code, so this is
+ * INVALID_STRUCTURE like actor sequence 0) and a canonical frontier
+ * (§28.1, §28.2, N6).
+ */
+export function snapshotPayloadFromCbor(value) {
+    const f = new Fields(value, "snapshot-payload", ALL_FIELDS);
+    const snapshotSeq = f.uint(3);
+    if (snapshotSeq === 0n)
+        f.fail(3, "(Snapshot Sequence) must be at least 1 (§29)");
+    return Object.freeze({
+        kind: "snapshot",
+        resourceId: resourceId(f.bytes(0, 32)),
+        dataEpoch: dataEpoch(f.uint(1)),
+        publisher: principalId(f.bytes(2, 32)),
+        snapshotSeq,
+        controlHead: controlRecordId(f.bytes(4, 32)),
+        frontier: canonicalFrontierFromCbor(f.any(5)),
+        ciphertext: f.bytes(6),
+    });
+}
+function decodePayload(payloadBytes, from) {
+    if (!(payloadBytes instanceof Uint8Array))
+        invalid("payload", "not a byte string");
+    return from(decodeDeterministic(payloadBytes));
+}
+function parseWith(bytes, from) {
+    const signed = parseSignedObject(bytes); // also applies N7 to the payload
+    return Object.freeze({ signed, payload: from(decodeStrict(signed.payloadBytes)) });
+}
+/** Decodes standalone payload bytes; they must be deterministic CBOR (N7). */
+export const decodeControlRecordPayload = (payloadBytes) => decodePayload(payloadBytes, controlRecordPayloadFromCbor);
+export const decodeDataUnitPayload = (payloadBytes) => decodePayload(payloadBytes, dataUnitPayloadFromCbor);
+export const decodeKeyPackagePayload = (payloadBytes) => decodePayload(payloadBytes, keyPackagePayloadFromCbor);
+export const decodeSnapshotPayload = (payloadBytes) => decodePayload(payloadBytes, snapshotPayloadFromCbor);
+/** Parses a received Control Record (§13) without verifying its signature. */
+export const parseControlRecord = (bytes) => parseWith(bytes, controlRecordPayloadFromCbor);
+/** Parses a received Data Unit (§26) without verifying its signature. */
+export const parseDataUnit = (bytes) => parseWith(bytes, dataUnitPayloadFromCbor);
+/** Parses a received Key Package (§25) without verifying its signature. */
+export const parseKeyPackage = (bytes) => parseWith(bytes, keyPackagePayloadFromCbor);
+/** Parses a received Snapshot (§29) without verifying its signature. */
+export const parseSnapshot = (bytes) => parseWith(bytes, snapshotPayloadFromCbor);
+/**
+ * The Principal that must have signed a data-plane object, read from its
+ * payload: the actor of a Data Unit (§26), the sender of a Key Package
+ * (§25) and the publisher of a Snapshot (§29). The caller resolves this ID to
+ * a Principal Descriptor and passes it to `verifySignedObject`; a `kid` that
+ * names anyone else fails as KID_MISMATCH (INVALID_SIGNATURE, G1/N2).
+ *
+ * Control Records have no hook: who must sign one depends on its type and on
+ * the chain (LFCP-019 to LFCP-021). Their payload's `issuer` is exposed as is.
+ */
+export function expectedSignerOf(payload) {
+    switch (payload.kind) {
+        case "data-unit":
+            return payload.actor;
+        case "key-package":
+            return payload.sender;
+        case "snapshot":
+            return payload.publisher;
+    }
+}
+//# sourceMappingURL=objects.js.map

package/dist/principal.d.ts

@@ -0,0 +1,43 @@
+import { type PrincipalId } from "@openlfcp/core";
+import { type CborMap, type CborValue } from "./cbor/index.js";
+/**
+ * A Principal Descriptor (LFCP-WIRE-01 §7): the public identity of a
+ * Principal. It holds public keys only; private keys stay in
+ * @openlfcp/crypto key pairs.
+ *
+ * CBOR: { 0 => principal-id, 1 => ed25519-public-key, 2 => x25519-public-key },
+ * every value a 32-byte byte string.
+ */
+export interface PrincipalDescriptor {
+    readonly principalId: PrincipalId;
+    readonly ed25519PublicKey: Uint8Array;
+    readonly x25519PublicKey: Uint8Array;
+}
+/** principal_id = SHA-256(ASCII("LFCP-PRINCIPAL-v1") || ed25519_public_key || x25519_public_key) (§7). */
+export declare function derivePrincipalId(ed25519PublicKey: Uint8Array, x25519PublicKey: Uint8Array): PrincipalId;
+/** Builds the descriptor for two public keys, deriving the Principal ID. */
+export declare function principalDescriptor(ed25519PublicKey: Uint8Array, x25519PublicKey: Uint8Array): PrincipalDescriptor;
+/** The descriptor for a Principal's key pairs. Only their public keys are read. */
+export declare function principalDescriptorFromKeys(signing: {
+    readonly publicKey: Uint8Array;
+}, agreement: {
+    readonly publicKey: Uint8Array;
+}): PrincipalDescriptor;
+/** The descriptor as a CBOR map, for embedding in larger Wire structures. */
+export declare function principalDescriptorToCbor(descriptor: PrincipalDescriptor): CborMap;
+/** Deterministic CBOR bytes of the descriptor (§5.2). */
+export declare function encodePrincipalDescriptor(descriptor: PrincipalDescriptor): Uint8Array;
+/**
+ * Validates a decoded descriptor: exactly the keys 0, 1 and 2 (the §7 map
+ * is closed), each a 32-byte byte string, and a Principal ID equal to the
+ * §7 hash of the two public keys ("A verifier MUST recompute the ID
+ * whenever a descriptor is received"), and an Ed25519 key that is a
+ * canonical point encoding not of small order (§7, §10.5.1).
+ */
+export declare function principalDescriptorFromCbor(value: CborValue): PrincipalDescriptor;
+/**
+ * Decodes received descriptor bytes. They must be deterministic CBOR
+ * (§5.2; CBOR_* errors otherwise) and a valid descriptor.
+ */
+export declare function decodePrincipalDescriptor(bytes: Uint8Array): PrincipalDescriptor;
+//# sourceMappingURL=principal.d.ts.map

package/dist/principal.js

@@ -0,0 +1,81 @@
+import { bytesEqual, LfcpError, principalId } from "@openlfcp/core";
+import { isValidEd25519PublicKey, sha256 } from "@openlfcp/crypto";
+import { cborMap, decodeStrict, encode, isCborMap, } from "./cbor/index.js";
+const KEY_LENGTH = 32;
+const DOMAIN = Uint8Array.from("LFCP-PRINCIPAL-v1", (c) => c.charCodeAt(0));
+function invalid(why) {
+    throw new LfcpError("INVALID_PRINCIPAL_DESCRIPTOR", `invalid Principal Descriptor: ${why}`);
+}
+function publicKey(kind, bytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.length !== KEY_LENGTH)
+        invalid(`${kind} must be a ${KEY_LENGTH}-byte byte string`);
+    return Uint8Array.from(bytes);
+}
+/** principal_id = SHA-256(ASCII("LFCP-PRINCIPAL-v1") || ed25519_public_key || x25519_public_key) (§7). */
+export function derivePrincipalId(ed25519PublicKey, x25519PublicKey) {
+    const ed = publicKey("the Ed25519 public key", ed25519PublicKey);
+    const x = publicKey("the X25519 public key", x25519PublicKey);
+    const input = new Uint8Array(DOMAIN.length + 2 * KEY_LENGTH);
+    input.set(DOMAIN, 0);
+    input.set(ed, DOMAIN.length);
+    input.set(x, DOMAIN.length + KEY_LENGTH);
+    return principalId(sha256(input));
+}
+/** Builds the descriptor for two public keys, deriving the Principal ID. */
+export function principalDescriptor(ed25519PublicKey, x25519PublicKey) {
+    return Object.freeze({
+        principalId: derivePrincipalId(ed25519PublicKey, x25519PublicKey),
+        ed25519PublicKey: Uint8Array.from(ed25519PublicKey),
+        x25519PublicKey: Uint8Array.from(x25519PublicKey),
+    });
+}
+/** The descriptor for a Principal's key pairs. Only their public keys are read. */
+export function principalDescriptorFromKeys(signing, agreement) {
+    return principalDescriptor(signing.publicKey, agreement.publicKey);
+}
+/** The descriptor as a CBOR map, for embedding in larger Wire structures. */
+export function principalDescriptorToCbor(descriptor) {
+    return cborMap([
+        [0, descriptor.principalId],
+        [1, descriptor.ed25519PublicKey],
+        [2, descriptor.x25519PublicKey],
+    ]);
+}
+/** Deterministic CBOR bytes of the descriptor (§5.2). */
+export function encodePrincipalDescriptor(descriptor) {
+    return encode(principalDescriptorToCbor(descriptor));
+}
+/**
+ * Validates a decoded descriptor: exactly the keys 0, 1 and 2 (the §7 map
+ * is closed), each a 32-byte byte string, and a Principal ID equal to the
+ * §7 hash of the two public keys ("A verifier MUST recompute the ID
+ * whenever a descriptor is received"), and an Ed25519 key that is a
+ * canonical point encoding not of small order (§7, §10.5.1).
+ */
+export function principalDescriptorFromCbor(value) {
+    if (!isCborMap(value))
+        invalid("not a map");
+    const fields = new Map(value.entries);
+    if (value.entries.length !== 3 || ![0, 1, 2].every((k) => fields.has(k)))
+        invalid("fields must be exactly 0, 1 and 2");
+    const id = publicKey("the Principal ID", fields.get(0));
+    const descriptor = principalDescriptor(publicKey("the Ed25519 public key", fields.get(1)), publicKey("the X25519 public key", fields.get(2)));
+    if (!bytesEqual(id, descriptor.principalId)) {
+        throw new LfcpError("PRINCIPAL_ID_MISMATCH", "the Principal ID does not match the descriptor's public keys");
+    }
+    if (!isValidEd25519PublicKey(descriptor.ed25519PublicKey))
+        invalid("the Ed25519 public key is not a canonical point encoding of large order");
+    return descriptor;
+}
+/**
+ * Decodes received descriptor bytes. They must be deterministic CBOR
+ * (§5.2; CBOR_* errors otherwise) and a valid descriptor.
+ */
+export function decodePrincipalDescriptor(bytes) {
+    const value = decodeStrict(bytes);
+    if (!bytesEqual(encode(value), bytes)) {
+        throw new LfcpError("CBOR_NON_CANONICAL", "descriptor bytes are not the deterministic encoding");
+    }
+    return principalDescriptorFromCbor(value);
+}
+//# sourceMappingURL=principal.js.map

package/dist/session-state.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The LFCP connection state machines (LFCP-WIRE-01 §63, §64) as pure
+ * transition functions: exactly the drawn edges, plus a connection-loss
+ * edge from every live state (G-SM1) and the CONNECTING failure edge
+ * (G-SM3). An event that has no edge from the current state returns
+ * undefined: the caller treats it as a protocol violation. No I/O.
+ *
+ * The per-resource sync machine (§65) belongs to the client sync session
+ * (LFCP-039a).
+ */
+/** §63 client connection states. */
+export type ClientConnectionState = "DISCONNECTED" | "CONNECTING" | "NEGOTIATING" | "AUTHENTICATING" | "READY";
+export type ClientConnectionEvent = 
+/** open WebSocket */
+"OPEN"
+/** WebSocket + lfcp-1 accepted */
+ | "CONNECTED"
+/** connection failed or lfcp-1 not accepted (G-SM3) */
+ | "CONNECT_FAILED"
+/** HELLO sent, CHALLENGE received */
+ | "CHALLENGED"
+/** AUTH sent, READY received */
+ | "READY_RECEIVED"
+/** open/close resources while READY */
+ | "RESOURCE"
+/** a fatal error during negotiation */
+ | "FATAL_ERROR" | "AUTH_FAILURE"
+/** the socket closed or the connection was lost (G-SM1) */
+ | "CONNECTION_LOST";
+/** The §63 client transition, or undefined when the event has no edge from `state`. */
+export declare function clientConnectionTransition(state: ClientConnectionState, event: ClientConnectionEvent): ClientConnectionState | undefined;
+/** §64 server session states. */
+export type ServerSessionState = "ACCEPTED" | "WAIT_HELLO" | "WAIT_AUTH" | "READY" | "CLOSED";
+export type ServerSessionEvent = 
+/** the session starts waiting for HELLO */
+"START"
+/** valid HELLO, CHALLENGE sent */
+ | "VALID_HELLO"
+/** valid AUTH, READY sent */
+ | "VALID_AUTH"
+/** an LFCP message on a READY session */
+ | "MESSAGE" | "PROTOCOL_VIOLATION" | "AUTH_FAILURE" | "FATAL_ERROR"
+/** the socket closed (G-SM1) */
+ | "SOCKET_CLOSED";
+/** The §64 server transition, or undefined when the event has no edge from `state`. */
+export declare function serverSessionTransition(state: ServerSessionState, event: ServerSessionEvent): ServerSessionState | undefined;
+//# sourceMappingURL=session-state.d.ts.map

package/dist/session-state.js

@@ -0,0 +1,49 @@
+/**
+ * The LFCP connection state machines (LFCP-WIRE-01 §63, §64) as pure
+ * transition functions: exactly the drawn edges, plus a connection-loss
+ * edge from every live state (G-SM1) and the CONNECTING failure edge
+ * (G-SM3). An event that has no edge from the current state returns
+ * undefined: the caller treats it as a protocol violation. No I/O.
+ *
+ * The per-resource sync machine (§65) belongs to the client sync session
+ * (LFCP-039a).
+ */
+const CLIENT = {
+    DISCONNECTED: { OPEN: "CONNECTING" },
+    CONNECTING: {
+        CONNECTED: "NEGOTIATING",
+        CONNECT_FAILED: "DISCONNECTED",
+        CONNECTION_LOST: "DISCONNECTED",
+    },
+    NEGOTIATING: {
+        CHALLENGED: "AUTHENTICATING",
+        FATAL_ERROR: "DISCONNECTED",
+        CONNECTION_LOST: "DISCONNECTED",
+    },
+    AUTHENTICATING: {
+        READY_RECEIVED: "READY",
+        AUTH_FAILURE: "DISCONNECTED",
+        CONNECTION_LOST: "DISCONNECTED",
+    },
+    READY: { RESOURCE: "READY", CONNECTION_LOST: "DISCONNECTED" },
+};
+/** The §63 client transition, or undefined when the event has no edge from `state`. */
+export function clientConnectionTransition(state, event) {
+    return CLIENT[state][event];
+}
+const SERVER = {
+    ACCEPTED: { START: "WAIT_HELLO", SOCKET_CLOSED: "CLOSED" },
+    WAIT_HELLO: {
+        VALID_HELLO: "WAIT_AUTH",
+        PROTOCOL_VIOLATION: "CLOSED",
+        SOCKET_CLOSED: "CLOSED",
+    },
+    WAIT_AUTH: { VALID_AUTH: "READY", AUTH_FAILURE: "CLOSED", SOCKET_CLOSED: "CLOSED" },
+    READY: { MESSAGE: "READY", FATAL_ERROR: "CLOSED", SOCKET_CLOSED: "CLOSED" },
+    CLOSED: {},
+};
+/** The §64 server transition, or undefined when the event has no edge from `state`. */
+export function serverSessionTransition(state, event) {
+    return SERVER[state][event];
+}
+//# sourceMappingURL=session-state.js.map

package/dist/snapshot.d.ts

@@ -0,0 +1,86 @@
+import { type ControlRecordId, type DataEpoch, type Hash32, type PrincipalId } from "@openlfcp/core";
+import { type ResourceDEK } from "@openlfcp/crypto";
+import { type Signer } from "./cose.js";
+import type { DataProfileCodec } from "./data-unit.js";
+import type { ControlView } from "./epoch.js";
+import { type ActorHave } from "./have.js";
+import { type Parsed, type SnapshotPayload } from "./objects.js";
+import type { PrincipalDescriptor } from "./principal.js";
+/** The fields of a Snapshot that its AAD binds (§29.1.3): payload fields 0-5. */
+export type SnapshotAadFields = Pick<SnapshotPayload, "resourceId" | "dataEpoch" | "publisher" | "snapshotSeq" | "controlHead" | "frontier">;
+/**
+ * §29.1.3: deterministic CBOR of ["LFCP-SNAPSHOT-v1", resource_id,
+ * data_epoch, publisher, snapshot_sequence, control_head,
+ * canonical_frontier]. The frontier must already be canonical: it is
+ * encoded as given and refused otherwise, never re-ordered.
+ */
+export declare function snapshotAad(fields: SnapshotAadFields): Uint8Array;
+/** The deterministic §29 payload, keys 0-6; checked by the receiver rules before it is returned. */
+export declare function encodeSnapshotPayload(fields: SnapshotAadFields & {
+    readonly ciphertext: Uint8Array;
+}): Uint8Array;
+export interface SealedSnapshot {
+    readonly bytes: Uint8Array;
+    /** §29: SHA-256 of the exact COSE_Sign1 bytes. */
+    readonly snapshotId: Hash32;
+}
+/**
+ * Encrypts `plaintext` and signs the Snapshot as `publisher` (the publisher
+ * field is the signer's Principal).
+ *
+ * BUILDING BLOCK: the sequence must come from a SnapshotSequenceReservation
+ * and never be reused for one (resource, epoch, publisher) (§29.1.2). Use
+ * createSnapshot (@openlfcp/client), which enforces that.
+ */
+export declare function sealSnapshot(fields: Omit<SnapshotAadFields, "publisher">, plaintext: Uint8Array, dek: ResourceDEK, publisher: Signer): SealedSnapshot;
+export type SnapshotRejectReason = "MALFORMED" | "OTHER_RESOURCE" | "UNKNOWN_PUBLISHER" | "SIGNATURE" | "UNKNOWN_CONTROL_HEAD" | "UNAUTHORIZED" | "UNKNOWN_EPOCH" | "BEYOND_CUTOFF";
+export interface SnapshotRejected {
+    readonly kind: "rejected";
+    readonly reason: SnapshotRejectReason;
+    readonly wireCode: "MALFORMED_MESSAGE" | "MISSING_DEPENDENCY" | "INVALID_SIGNATURE" | "AUTHORIZATION_FAILED" | "STALE_DATA_EPOCH";
+    readonly message: string;
+}
+export type SnapshotCheck = {
+    readonly kind: "valid";
+    readonly parsed: Parsed<SnapshotPayload>;
+    readonly snapshotId: Hash32;
+} | SnapshotRejected;
+export interface SnapshotCheckOptions {
+    /** Resolves a publisher that no record of the chain describes. */
+    readonly resolvePrincipal?: (id: PrincipalId) => PrincipalDescriptor | undefined;
+}
+/** Steps 1-8: everything that needs no DEK, for servers and clients. */
+export declare function checkSnapshot(view: ControlView, bytes: Uint8Array, options?: SnapshotCheckOptions): SnapshotCheck;
+/**
+ * §29 (G-EP4): once a Key Epoch closes the Snapshot's epoch, the Snapshot
+ * may cover only units within that epoch's final frontier; units beyond it
+ * are quarantined (§19.1), so a Snapshot that includes them would merge
+ * stale work. Evaluated against the latest known state, as §19.1 does for
+ * Data Units. Returns why, or undefined when within.
+ */
+export declare function beyondCutoff(view: ControlView, epoch: DataEpoch, frontier: readonly ActorHave[]): string | undefined;
+export type ReceivedSnapshot<T> = {
+    readonly kind: "accepted";
+    readonly snapshotId: Hash32;
+    readonly publisher: PrincipalId;
+    readonly seq: bigint;
+    readonly epoch: DataEpoch;
+    readonly controlHead: ControlRecordId;
+    readonly frontier: readonly ActorHave[];
+    readonly value: T;
+} | SnapshotRejected
+/** Client-local: no wire code (§29.1.4); surface it to the application. */
+ | {
+    readonly kind: "local-failure";
+    readonly reason: "NO_DEK" | "DEK_COMMITMENT_MISMATCH" | "AEAD" | "PROFILE_REJECTED";
+    readonly snapshotId: Hash32;
+    readonly message: string;
+};
+export interface ReceiveSnapshotOptions<T> extends SnapshotCheckOptions {
+    readonly dek: (epoch: DataEpoch) => ResourceDEK | undefined | Promise<ResourceDEK | undefined>;
+    /** The Data Profile's Snapshot codec: decodes and validates the Snapshot plaintext. */
+    readonly profile: DataProfileCodec<T>;
+}
+/** A received Snapshot end to end (steps 1-10). Only "accepted" may be loaded. */
+export declare function receiveSnapshot<T>(view: ControlView, bytes: Uint8Array, options: ReceiveSnapshotOptions<T>): Promise<ReceivedSnapshot<T>>;
+//# sourceMappingURL=snapshot.d.ts.map