@openlfcp/wire 0.1.0-rc.1

package/dist/endpoint.js

@@ -0,0 +1,116 @@
+import { LfcpError } from "@openlfcp/core";
+import { cborMap } from "./cbor/index.js";
+import { Fields } from "./fields.js";
+/**
+ * Decodes an `endpoint` map: exactly keys 0 (tstr) and 1 (uint), optional
+ * 2 (uint). A violation is INVALID_STRUCTURE (MALFORMED_MESSAGE on the wire).
+ *
+ * Structure only. Reserved flag bits are kept: "A writer sets reserved bits
+ * to 0; a receiver ignores them" (§16). The receiver's URL scheme rule is
+ * checkReceivedUrl, applied by the Control Record decoders.
+ */
+export function endpointFromCbor(value) {
+    const f = new Fields(value, "endpoint", [0, 1], [2]);
+    const url = f.text(0);
+    const priority = f.uint(1);
+    return Object.freeze(f.has(2) ? { url, priority, flags: f.uint(2) } : { url, priority });
+}
+/** The §16 flag bits LFCP-WIRE-01 defines (0-5); all other bits are reserved. */
+export const ENDPOINT_FLAGS = Object.freeze({
+    DATA_PLANE_STORAGE: 1n << 0n,
+    CONTROL_PLANE_STORAGE: 1n << 1n,
+    SNAPSHOTS: 1n << 2n,
+    PRESENCE: 1n << 3n,
+    PREFERRED_FOR_READS: 1n << 4n,
+    PREFERRED_FOR_WRITES: 1n << 5n,
+});
+const DEFINED_FLAGS = 63n;
+const UINT64_MAX = 2n ** 64n - 1n;
+function refuse(why) {
+    throw new LfcpError("INVALID_STRUCTURE", `refusing to write an endpoint: ${why}`);
+}
+/**
+ * §16, receiver side: "A receiver MUST reject a record carrying such a URL
+ * [an endpoint or Control Coordinator URL in a Control Record] with any
+ * scheme other than ws or wss with MALFORMED_MESSAGE." The scheme is
+ * compared case-insensitively (RFC 3986 §3.1) and must be followed by
+ * "://", so a URL without an authority (wss:host) is rejected too. The
+ * loopback rule is the sender's. Throws INVALID_STRUCTURE.
+ */
+export function checkReceivedUrl(url) {
+    const m = /^([A-Za-z][A-Za-z0-9+.-]*):(\/\/)?/.exec(url);
+    const scheme = m?.[1]?.toLowerCase();
+    if (scheme !== "ws" && scheme !== "wss")
+        throw new LfcpError("INVALID_STRUCTURE", `an endpoint or coordinator URL must use ws or wss, not ${scheme ?? "no scheme"} (§16)`);
+    if (m?.[2] === undefined)
+        throw new LfcpError("INVALID_STRUCTURE", `an endpoint or coordinator URL must start with ${scheme}:// (§16)`);
+}
+/**
+ * Checks a URL an LFCP writer puts in an endpoint or a coordinator field
+ * (§16: "A sender uses wss://, except ws:// for a loopback address").
+ *
+ * Accepted: an absolute URI (RFC 3986 §4.3: no fragment) with scheme wss,
+ * or ws on a loopback host (localhost, 127.0.0.0/8, [::1]).
+ */
+export function checkWriterUrl(url) {
+    if (typeof url !== "string")
+        refuse("the URL must be a text string");
+    const control = [...url].some((ch) => {
+        const c = ch.codePointAt(0);
+        return c < 0x20 || c === 0x7f;
+    });
+    if (control || /\s/.test(url))
+        refuse("the URL contains whitespace or control characters");
+    // Split by hand: the former /^scheme:\/\/([^/?#]+)([^#]*)$/ backtracked
+    // quadratically on a long URL ending in "#" (security review, H3 pass).
+    // Same result: the authority runs to the first "/", "?" or "#" and must
+    // not be empty, and no "#" (fragment) may follow.
+    const m = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(url);
+    const rest = m === null ? "" : url.slice(m[0].length);
+    const cut = rest.search(/[/?#]/);
+    const authority = cut < 0 ? rest : rest.slice(0, cut);
+    if (m === null || authority === "" || rest.includes("#"))
+        refuse("not an absolute URL with an authority and no fragment");
+    const scheme = m[1].toLowerCase();
+    if (authority.includes("@"))
+        refuse("user information is not allowed in the URL");
+    const host = (/^(\[[^\]]*\]|[^:]*)(:\d*)?$/.exec(authority)?.[1] ?? "").toLowerCase();
+    if (host === "")
+        refuse("the URL has no host");
+    const loopback = host === "localhost" || host === "[::1]" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+    if (scheme === "wss")
+        return;
+    if (scheme === "ws" && loopback)
+        return;
+    refuse(scheme === "ws"
+        ? "ws:// is only for loopback hosts; use wss://"
+        : `scheme ${scheme} is not wss`);
+}
+/**
+ * Encodes an endpoint for a record this SDK writes. Writer rules: the URL
+ * passes checkWriterUrl, the priority and flags are uint64, and no
+ * reserved flag bit (6 and up) is set.
+ */
+export function endpointToCbor(endpoint) {
+    checkWriterUrl(endpoint.url);
+    const uint = (what, n) => {
+        if (typeof n !== "bigint" || n < 0n || n > UINT64_MAX)
+            refuse(`${what} must be a uint64 bigint`);
+        return n;
+    };
+    const priority = uint("the priority", endpoint.priority);
+    if (endpoint.flags === undefined)
+        return cborMap([
+            [0, endpoint.url],
+            [1, priority],
+        ]);
+    const flags = uint("the flags", endpoint.flags);
+    if ((flags & ~DEFINED_FLAGS) !== 0n)
+        refuse("reserved flag bits (6 and up) must not be set");
+    return cborMap([
+        [0, endpoint.url],
+        [1, priority],
+        [2, flags],
+    ]);
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/epoch.d.ts

@@ -0,0 +1,109 @@
+import { type ControlRecordId, type DataEpoch, type Hash32, type PrincipalId } from "@openlfcp/core";
+import { type ResourceDEK } from "@openlfcp/crypto";
+import type { ChainResult, ControlState } from "./chain.js";
+import type { Signer } from "./cose.js";
+import type { ActorHave } from "./have.js";
+import type { DataUnitPayload } from "./objects.js";
+/**
+ * Data Epoch rotation and the strict previous-epoch cutoff (LFCP-WIRE-01
+ * §19, §19.1, §26.3 steps 4-5, §75, §88 step 7).
+ *
+ * After KEY_EPOCH(E + 1) closes epoch E with a final frontier, a Data Unit
+ * of epoch E is automatically acceptable only when its actor and sequence
+ * are inside that frontier. Anything else is stale offline work: it is
+ * quarantined (STALE_DATA_EPOCH), never merged automatically and never
+ * dropped silently, and never re-encrypted into a newer epoch. Units within
+ * the cutoff stay valid history, and rotation does not take back what a
+ * removed member already decrypted (§75).
+ *
+ * Everything except rotateEpoch (which draws a fresh DEK) is pure.
+ */
+/** §19 Key Epoch reason codes. Unknown codes are kept by the decoder (structure only). */
+export declare const KEY_EPOCH_REASON: Readonly<{
+    ROUTINE: 0n;
+    MEMBER_REVOKED: 1n;
+    COMPROMISE: 2n;
+    OWNERSHIP_TRANSFER: 3n;
+    MANUAL_SECURITY: 4n;
+}>;
+/**
+ * Whether `seq` of `principal` is inside a final frontier: within the
+ * actor's contiguous run (1..contiguous) or one of its explicit extra
+ * ranges. An actor absent from the frontier covers nothing (§19.1).
+ */
+export declare function isSequenceWithinFrontier(principal: PrincipalId, seq: bigint, frontier: readonly ActorHave[]): boolean;
+/** A validated chain, as needed to place a unit: its latest state and its state at any head. */
+export type ControlView = Pick<Extract<ChainResult, {
+    kind: "linear";
+}>, "state" | "stateAt">;
+/** The Data Unit fields the epoch rules read. */
+export type DataUnitHeader = Pick<DataUnitPayload, "resourceId" | "dataEpoch" | "actor" | "actorSeq" | "controlHead">;
+export type EpochClassification = {
+    readonly kind: "accept";
+}
+/**
+ * Stale offline work: never merged automatically, never dropped
+ * silently; surface it to the application for manual review (§19.1).
+ */
+ | {
+    readonly kind: "quarantine";
+    readonly code: "STALE_DATA_EPOCH";
+    readonly reason: "BEYOND_CUTOFF" | "ACTOR_ABSENT";
+    readonly epoch: DataEpoch;
+    /** The Key Epoch record whose final frontier excludes the unit. */
+    readonly closedBy: ControlRecordId;
+} | {
+    readonly kind: "reject";
+    readonly reason: "UNKNOWN_CONTROL_HEAD" | "UNKNOWN_EPOCH" | "OTHER_RESOURCE";
+    readonly wireCode: "MISSING_DEPENDENCY" | "MALFORMED_MESSAGE";
+};
+/**
+ * The epoch-eligibility of a Data Unit (§26.3 steps 4-5).
+ *
+ * - The unit's referenced Control Head must be on the chain, and its epoch
+ *   recognized at that head. Otherwise MISSING_DEPENDENCY (§26.3, G-EP2):
+ *   the receiver lacks Control records, or the unit claims a future epoch.
+ * - The cutoff is evaluated against the LATEST known state (§19.1, §26.3,
+ *   G-EP1). Once a Key Epoch closing the unit's epoch is known, the unit is
+ *   held to its final frontier, whichever head the unit referenced (vector
+ *   §12.5: D3 is stale "after C6 is known").
+ *
+ * Signature, data/write authority at the referenced head and AEAD are
+ * checked by the Data Unit verifier (LFCP-025), which calls this hook.
+ */
+export declare function classifyDataUnit(view: ControlView, unit: DataUnitHeader): EpochClassification;
+export type DataPutDecision = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly nack: "STALE_DATA_EPOCH" | "MISSING_DEPENDENCY" | "MALFORMED_MESSAGE";
+    readonly reason: string;
+};
+/**
+ * The server's epoch check for one unit of a DATA_PUT (§75: "A server that
+ * receives such a unit in DATA_PUT responds NACK(STALE_DATA_EPOCH)"). The
+ * other §51 checks (structure, signature, size, hosting policy) are the
+ * caller's.
+ */
+export declare function serverAcceptsDataPut(view: ControlView, unit: DataUnitHeader): DataPutDecision;
+/** A new Key Epoch: the record to submit, and the fresh DEK, which never goes into the record. */
+export interface EpochRotation {
+    readonly bytes: Uint8Array;
+    readonly recordId: ControlRecordId;
+    readonly epoch: DataEpoch;
+    /** The new epoch's DEK: deliver it in Key Packages (LFCP-024), never in a Control record. */
+    readonly dek: ResourceDEK;
+    readonly dekCommitment: Hash32;
+}
+/**
+ * Builds KEY_EPOCH(current + 1) on the current head: a fresh random DEK
+ * (LFCP-018; never the previous one), its §11 commitment, the closing
+ * epoch's canonical final frontier and a §19 reason. Submit it with
+ * CONTROL_PUT (proposeControlTransition); the issuer needs key/rotate.
+ */
+export declare function rotateEpoch(state: ControlState, signer: Signer, options: {
+    readonly reason: bigint;
+    readonly finalFrontier: readonly ActorHave[];
+    readonly dek?: ResourceDEK;
+}): EpochRotation;
+//# sourceMappingURL=epoch.d.ts.map

package/dist/epoch.js

@@ -0,0 +1,128 @@
+import { bytesEqual, dataEpoch, } from "@openlfcp/core";
+import { dekCommitment as commitmentOf, generateResourceDEK, } from "@openlfcp/crypto";
+import { signControlRecord } from "./control.js";
+/**
+ * Data Epoch rotation and the strict previous-epoch cutoff (LFCP-WIRE-01
+ * §19, §19.1, §26.3 steps 4-5, §75, §88 step 7).
+ *
+ * After KEY_EPOCH(E + 1) closes epoch E with a final frontier, a Data Unit
+ * of epoch E is automatically acceptable only when its actor and sequence
+ * are inside that frontier. Anything else is stale offline work: it is
+ * quarantined (STALE_DATA_EPOCH), never merged automatically and never
+ * dropped silently, and never re-encrypted into a newer epoch. Units within
+ * the cutoff stay valid history, and rotation does not take back what a
+ * removed member already decrypted (§75).
+ *
+ * Everything except rotateEpoch (which draws a fresh DEK) is pure.
+ */
+/** §19 Key Epoch reason codes. Unknown codes are kept by the decoder (structure only). */
+export const KEY_EPOCH_REASON = Object.freeze({
+    ROUTINE: 0n,
+    MEMBER_REVOKED: 1n,
+    COMPROMISE: 2n,
+    OWNERSHIP_TRANSFER: 3n,
+    MANUAL_SECURITY: 4n,
+});
+/**
+ * Whether `seq` of `principal` is inside a final frontier: within the
+ * actor's contiguous run (1..contiguous) or one of its explicit extra
+ * ranges. An actor absent from the frontier covers nothing (§19.1).
+ */
+export function isSequenceWithinFrontier(principal, seq, frontier) {
+    const have = frontier.find((h) => bytesEqual(h.principalId, principal));
+    if (have === undefined || seq < 1n)
+        return false;
+    return seq <= have.contiguous || have.extras.some(([start, end]) => start <= seq && seq <= end);
+}
+/**
+ * The epoch-eligibility of a Data Unit (§26.3 steps 4-5).
+ *
+ * - The unit's referenced Control Head must be on the chain, and its epoch
+ *   recognized at that head. Otherwise MISSING_DEPENDENCY (§26.3, G-EP2):
+ *   the receiver lacks Control records, or the unit claims a future epoch.
+ * - The cutoff is evaluated against the LATEST known state (§19.1, §26.3,
+ *   G-EP1). Once a Key Epoch closing the unit's epoch is known, the unit is
+ *   held to its final frontier, whichever head the unit referenced (vector
+ *   §12.5: D3 is stale "after C6 is known").
+ *
+ * Signature, data/write authority at the referenced head and AEAD are
+ * checked by the Data Unit verifier (LFCP-025), which calls this hook.
+ */
+export function classifyDataUnit(view, unit) {
+    if (!bytesEqual(unit.resourceId, view.state.resourceId))
+        return Object.freeze({
+            kind: "reject",
+            reason: "OTHER_RESOURCE",
+            wireCode: "MALFORMED_MESSAGE",
+        });
+    const atHead = view.stateAt(unit.controlHead);
+    if (atHead === undefined)
+        return Object.freeze({
+            kind: "reject",
+            reason: "UNKNOWN_CONTROL_HEAD",
+            wireCode: "MISSING_DEPENDENCY",
+        });
+    if (!atHead.epochs.has(String(unit.dataEpoch)))
+        return Object.freeze({
+            kind: "reject",
+            reason: "UNKNOWN_EPOCH",
+            wireCode: "MISSING_DEPENDENCY",
+        });
+    const latest = view.state.epochs.get(String(unit.dataEpoch));
+    if (latest === undefined || latest.finalFrontier === null || latest.closedBy === null)
+        return Object.freeze({ kind: "accept" });
+    if (isSequenceWithinFrontier(unit.actor, unit.actorSeq, latest.finalFrontier))
+        return Object.freeze({ kind: "accept" });
+    const absent = !latest.finalFrontier.some((h) => bytesEqual(h.principalId, unit.actor));
+    return Object.freeze({
+        kind: "quarantine",
+        code: "STALE_DATA_EPOCH",
+        reason: absent ? "ACTOR_ABSENT" : "BEYOND_CUTOFF",
+        epoch: unit.dataEpoch,
+        closedBy: latest.closedBy,
+    });
+}
+/**
+ * The server's epoch check for one unit of a DATA_PUT (§75: "A server that
+ * receives such a unit in DATA_PUT responds NACK(STALE_DATA_EPOCH)"). The
+ * other §51 checks (structure, signature, size, hosting policy) are the
+ * caller's.
+ */
+export function serverAcceptsDataPut(view, unit) {
+    const c = classifyDataUnit(view, unit);
+    if (c.kind === "accept")
+        return Object.freeze({ ok: true });
+    if (c.kind === "quarantine")
+        return Object.freeze({
+            ok: false,
+            nack: "STALE_DATA_EPOCH",
+            reason: `${c.reason}: outside the final frontier of epoch ${c.epoch}`,
+        });
+    return Object.freeze({ ok: false, nack: c.wireCode, reason: c.reason });
+}
+/**
+ * Builds KEY_EPOCH(current + 1) on the current head: a fresh random DEK
+ * (LFCP-018; never the previous one), its §11 commitment, the closing
+ * epoch's canonical final frontier and a §19 reason. Submit it with
+ * CONTROL_PUT (proposeControlTransition); the issuer needs key/rotate.
+ */
+export function rotateEpoch(state, signer, options) {
+    const epoch = dataEpoch(state.epoch.epoch + 1n);
+    const dek = options.dek ?? generateResourceDEK();
+    const dekCommitment = commitmentOf(state.resourceId, epoch, dek);
+    const signed = signControlRecord({ resourceId: state.resourceId, controlSeq: state.seq + 1n, prevControlId: state.head }, {
+        type: "KEY_EPOCH",
+        epoch,
+        dekCommitment,
+        finalFrontier: options.finalFrontier,
+        reason: options.reason,
+    }, signer);
+    return Object.freeze({
+        bytes: signed.bytes,
+        recordId: signed.recordId,
+        epoch,
+        dek,
+        dekCommitment,
+    });
+}
+//# sourceMappingURL=epoch.js.map

package/dist/fields.d.ts

@@ -0,0 +1,18 @@
+import { type CborValue } from "./cbor/index.js";
+export declare function invalid(what: string, why: string): never;
+/** Fields of a map whose key set must be `required` plus any of `optional`, nothing else. */
+export declare class Fields {
+    #private;
+    constructor(value: CborValue, what: string, required: readonly number[], optional?: readonly number[]);
+    has(key: number): boolean;
+    fail(key: number, why: string): never;
+    any(key: number): CborValue;
+    uint(key: number): bigint;
+    bytes(key: number, length?: number): Uint8Array;
+    bytesOrNull(key: number, length: number): Uint8Array | null;
+    text(key: number): string;
+    array(key: number): readonly CborValue[];
+    /** An array of unsigned integers; `nonEmpty` for CDDL `[1* uint]`. */
+    uintArray(key: number, nonEmpty: boolean): readonly bigint[];
+}
+//# sourceMappingURL=fields.d.ts.map

package/dist/fields.js

@@ -0,0 +1,78 @@
+import { LfcpError } from "@openlfcp/core";
+import { isCborMap } from "./cbor/index.js";
+// Readers for the integer-keyed maps of LFCP-WIRE-01 structures. Every
+// failure is INVALID_STRUCTURE (MALFORMED_MESSAGE on the wire). Values are
+// copied out of the decoded CBOR; nothing here encodes.
+export function invalid(what, why) {
+    throw new LfcpError("INVALID_STRUCTURE", `invalid ${what}: ${why}`);
+}
+/** Fields of a map whose key set must be `required` plus any of `optional`, nothing else. */
+export class Fields {
+    #what;
+    #map;
+    constructor(value, what, required, optional = []) {
+        this.#what = what;
+        if (!isCborMap(value))
+            invalid(what, "not a map");
+        const allowed = new Set([...required, ...optional]);
+        this.#map = new Map();
+        for (const [key, field] of value.entries) {
+            if (typeof key !== "number" || !allowed.has(key))
+                invalid(what, `field ${String(key)} is not allowed`);
+            this.#map.set(key, field);
+        }
+        for (const key of required)
+            if (!this.#map.has(key))
+                invalid(what, `field ${key} is missing`);
+    }
+    has(key) {
+        return this.#map.has(key);
+    }
+    fail(key, why) {
+        invalid(this.#what, `field ${key} ${why}`);
+    }
+    any(key) {
+        return this.#map.get(key);
+    }
+    uint(key) {
+        const v = this.#map.get(key);
+        if ((typeof v === "number" || typeof v === "bigint") && v >= 0)
+            return BigInt(v);
+        this.fail(key, "must be an unsigned integer");
+    }
+    bytes(key, length) {
+        const v = this.#map.get(key);
+        if (!(v instanceof Uint8Array))
+            this.fail(key, "must be a byte string");
+        if (length !== undefined && v.length !== length)
+            this.fail(key, `must be ${length} bytes`);
+        return Uint8Array.from(v);
+    }
+    bytesOrNull(key, length) {
+        return this.#map.get(key) === null ? null : this.bytes(key, length);
+    }
+    text(key) {
+        const v = this.#map.get(key);
+        if (typeof v !== "string")
+            this.fail(key, "must be a text string");
+        return v;
+    }
+    array(key) {
+        const v = this.#map.get(key);
+        if (!Array.isArray(v))
+            this.fail(key, "must be an array");
+        return v;
+    }
+    /** An array of unsigned integers; `nonEmpty` for CDDL `[1* uint]`. */
+    uintArray(key, nonEmpty) {
+        const list = this.array(key);
+        if (nonEmpty && list.length === 0)
+            this.fail(key, "must not be empty");
+        return Object.freeze(list.map((v) => {
+            if ((typeof v === "number" || typeof v === "bigint") && v >= 0)
+                return BigInt(v);
+            return this.fail(key, "must hold unsigned integers only");
+        }));
+    }
+}
+//# sourceMappingURL=fields.js.map

package/dist/handshake.d.ts

@@ -0,0 +1,175 @@
+import { type PrincipalId } from "@openlfcp/core";
+import { type Signer } from "./cose.js";
+import { type AnyMessage, type LfcpMessage } from "./message.js";
+import { type PrincipalDescriptor } 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 declare const WIRE_PROFILE = "LFCP-WIRE-01";
+/**
+ * A source of random bytes. Production code leaves it out (the platform
+ * CSPRNG, core secureRandom). Passing one is FOR TESTS ONLY: reproducible
+ * nonces and session IDs defeat the handshake's freshness.
+ */
+export type RandomSource = (length: number) => Uint8Array;
+/** The values the §36 transcript binds. */
+export interface AuthTranscriptFields {
+    readonly sessionId: Uint8Array;
+    readonly clientNonce: Uint8Array;
+    readonly serverNonce: Uint8Array;
+    readonly serverId: Uint8Array;
+    readonly principalId: PrincipalId;
+}
+/**
+ * §36: deterministic CBOR of ["LFCP-AUTH-v1", session_id, client_nonce,
+ * server_nonce, server_id, principal_id]; nothing else.
+ */
+export declare function authTranscript(f: AuthTranscriptFields): Uint8Array;
+/** Decodes an auth transcript strictly: deterministic CBOR, the label, six elements, exact sizes. */
+export declare function decodeAuthTranscript(bytes: Uint8Array): AuthTranscriptFields;
+/** The AUTH proof: a §10 COSE_Sign1 by the session Principal over the exact transcript. */
+export declare function signAuthProof(fields: AuthTranscriptFields, signer: Signer): Uint8Array;
+export type AuthProofCheck = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly reason: "MALFORMED" | "TRANSCRIPT_MISMATCH" | "KID_MISMATCH" | "BAD_SIGNATURE";
+};
+/**
+ * §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 declare function verifyAuthProof(proof: Uint8Array, expected: AuthTranscriptFields, principal: PrincipalDescriptor): AuthProofCheck;
+/** The result of a successful handshake: who the session is, never what it may do. */
+export interface AuthenticatedSession {
+    readonly principal: PrincipalDescriptor;
+    readonly wireProfile: string;
+    readonly sessionId: Uint8Array;
+    readonly serverId: Uint8Array;
+    readonly dataProfiles?: readonly string[];
+    /** The opaque hosting/account credential from AUTH: server policy only, not Resource authority. */
+    readonly credential?: Uint8Array;
+}
+/**
+ * §34 profile negotiation: the first profile the client offers that the
+ * server supports, or undefined.
+ */
+export declare const selectWireProfile: (offered: readonly string[], supported: readonly string[]) => string | undefined;
+/** Whether a message type is a Resource, Control, Data, Key, Snapshot or Presence message. */
+export declare const isResourceMessage: (type: AnyMessage["type"]) => boolean;
+export interface ServerHandshakeConfig {
+    /** The stable 32-byte server ID, from server state; never derived from host, TLS or session values. */
+    readonly serverId: Uint8Array;
+    readonly wireProfiles: readonly string[];
+    readonly maxMessageBytes: bigint;
+    /** §37 durability level 0-3; an ACK must never claim more. */
+    readonly durability: bigint;
+    readonly heartbeatMs: bigint;
+    readonly extensions?: readonly string[];
+    /** TESTS ONLY (see RandomSource). */
+    readonly random?: RandomSource;
+}
+export type ServerSession = {
+    readonly phase: "WAIT_HELLO";
+} | {
+    readonly phase: "WAIT_AUTH";
+    readonly principal: PrincipalDescriptor;
+    readonly clientNonce: Uint8Array;
+    readonly dataProfiles?: readonly string[];
+    readonly wireProfile: string;
+    readonly serverNonce: Uint8Array;
+    readonly sessionId: Uint8Array;
+} | {
+    readonly phase: "READY";
+    readonly session: AuthenticatedSession;
+} | {
+    readonly phase: "CLOSED";
+    readonly reason: string;
+};
+/** What the server does after one received message. */
+export interface ServerStep {
+    readonly session: ServerSession;
+    /** Messages to send, in order. */
+    readonly send: readonly AnyMessage[];
+    /** Close the connection after sending. */
+    readonly close: boolean;
+    /** A READY-state message for the server's Resource logic. */
+    readonly deliver?: AnyMessage;
+}
+/** §64: ACCEPTED moves straight to WAIT_HELLO. */
+export declare const startServerSession: () => ServerSession;
+/**
+ * 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 declare function serverReceive(session: ServerSession, message: AnyMessage, config: ServerHandshakeConfig): ServerStep;
+export interface ClientHandshakeConfig {
+    readonly signer: Signer;
+    readonly wireProfiles?: readonly string[];
+    readonly dataProfiles?: readonly string[];
+    /** An opaque hosting/account credential for AUTH (§36); server policy only. */
+    readonly credential?: Uint8Array;
+    /** The server ID the client expects, when it knows it (e.g. from a Route Manifest). */
+    readonly expectedServerId?: Uint8Array;
+    /** TESTS ONLY (see RandomSource). */
+    readonly random?: RandomSource;
+}
+/** The parameters READY grants the session (§37). */
+export interface ReadySession {
+    readonly wireProfile: string;
+    readonly serverId: Uint8Array;
+    readonly sessionId: Uint8Array;
+    readonly maxMessageBytes: bigint;
+    readonly durability: bigint;
+    readonly heartbeatMs: bigint;
+    readonly extensions: readonly string[];
+}
+export type ClientSession = {
+    readonly phase: "NEGOTIATING";
+    readonly hello: LfcpMessage<"HELLO">;
+} | {
+    readonly phase: "AUTHENTICATING";
+    readonly hello: LfcpMessage<"HELLO">;
+    readonly wireProfile: string;
+    readonly serverId: Uint8Array;
+    readonly sessionId: Uint8Array;
+} | {
+    readonly phase: "READY";
+    readonly ready: ReadySession;
+} | {
+    readonly phase: "DISCONNECTED";
+    readonly reason: string;
+};
+export interface ClientStep {
+    readonly session: ClientSession;
+    readonly send: readonly AnyMessage[];
+    readonly close: boolean;
+    readonly deliver?: AnyMessage;
+}
+/** Starts the handshake once the WebSocket with lfcp-1 is open: the HELLO to send (§34). */
+export declare function startClientHandshake(config: ClientHandshakeConfig): ClientStep;
+/**
+ * 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 declare function clientReceive(session: ClientSession, message: AnyMessage, config: ClientHandshakeConfig): ClientStep;
+//# sourceMappingURL=handshake.d.ts.map