@openlfcp/wire 0.1.0-rc.1

package/dist/chain.js

@@ -0,0 +1,339 @@
+import { controlRecordId, dataEpoch, LfcpError, toHex, } from "@openlfcp/core";
+import { applyCapabilities, authorizeControlRecord, transferIssuerDescriptor, } from "./capability.js";
+import { controlRecordSigner, decodeControlRecord, verifyGenesis, } from "./control.js";
+import { objectId, verifySignedObject } from "./cose.js";
+const WIRE = {
+    MALFORMED: "MALFORMED_MESSAGE",
+    // §14: "Unknown core Control Record types MUST cause validation failure, with INVALID_CONTROL_CHAIN."
+    UNSUPPORTED_TYPE: "INVALID_CONTROL_CHAIN",
+    // §13.1: a broken chain structure is INVALID_CONTROL_CHAIN.
+    NO_GENESIS: "INVALID_CONTROL_CHAIN",
+    // §15: a Genesis whose issuer or kid is not its owner.
+    GENESIS_SIGNER: "INVALID_SIGNATURE",
+    RESOURCE: "INVALID_CONTROL_CHAIN",
+    SEQUENCE: "INVALID_CONTROL_CHAIN",
+    PREVIOUS: "INVALID_CONTROL_CHAIN",
+    // §13: kid MUST equal the issuer, and the signature must verify; §23.3 transfer signatures.
+    SIGNATURE: "INVALID_SIGNATURE",
+    // §13.1: an issuer the receiver cannot resolve to a Principal Descriptor.
+    UNRESOLVED_ISSUER: "MISSING_DEPENDENCY",
+    // §19 (G-EP3): a Key Epoch that is not current + 1 breaks the chain.
+    EPOCH: "INVALID_CONTROL_CHAIN",
+    UNAUTHORIZED: "AUTHORIZATION_FAILED",
+    // MVP-0.1-PROTOCOL-SCOPE §4 (DV1): Coordinator Recovery and Resource Tombstone records.
+    DEFERRED_TYPE: "PROTOCOL_UNSUPPORTED",
+};
+const SDK_CODE = {
+    MALFORMED: "INVALID_STRUCTURE",
+    UNSUPPORTED_TYPE: "UNSUPPORTED_VALUE",
+    NO_GENESIS: "INVALID_CONTROL_CHAIN",
+    GENESIS_SIGNER: "INVALID_SIGNATURE",
+    RESOURCE: "INVALID_CONTROL_CHAIN",
+    SEQUENCE: "INVALID_CONTROL_CHAIN",
+    PREVIOUS: "INVALID_CONTROL_CHAIN",
+    SIGNATURE: "INVALID_SIGNATURE",
+    UNRESOLVED_ISSUER: "MISSING_DEPENDENCY",
+    EPOCH: "INVALID_CONTROL_CHAIN",
+    UNAUTHORIZED: "AUTHORIZATION_FAILED",
+    DEFERRED_TYPE: "PROTOCOL_UNSUPPORTED",
+};
+function problem(kind, at, message, cause) {
+    return { problem: kind, ...at, error: cause ?? new LfcpError(SDK_CODE[kind], message) };
+}
+/** The record ID: SHA-256 of the exact signed bytes (§13), as a ControlRecordId. */
+const rid = (record) => controlRecordId(record.signed.id);
+const at = (e) => ({
+    index: e.index,
+    recordId: rid(e.record),
+    seq: e.record.payload.controlSeq,
+});
+/** The first problem by (sequence, record ID): reproducible across input orders. */
+function invalid(problems) {
+    const first = [...problems].sort((a, b) => {
+        if (a.seq !== b.seq)
+            return a.seq < b.seq ? -1 : 1;
+        const x = a.recordId === null ? "" : toHex(a.recordId);
+        const y = b.recordId === null ? "" : toHex(b.recordId);
+        return x < y ? -1 : x > y ? 1 : 0;
+    })[0];
+    return Object.freeze({
+        kind: "invalid",
+        problem: first.problem,
+        wireCode: WIRE[first.problem],
+        index: first.index,
+        recordId: first.recordId,
+        error: first.error,
+    });
+}
+const sortedIds = (ids) => Object.freeze([...ids].sort((a, b) => (toHex(a) < toHex(b) ? -1 : 1)));
+function conflict(commonHead, seq, competing, prefixState) {
+    return Object.freeze({
+        kind: "conflict",
+        wireCode: "CONTROL_CONFLICT",
+        commonHead,
+        seq,
+        competing: sortedIds(competing),
+        prefixState,
+    });
+}
+function genesisState(record) {
+    const body = record.body;
+    if (body.type !== "GENESIS")
+        throw new Error("not a Genesis record");
+    const id = controlRecordId(record.signed.id);
+    return Object.freeze({
+        resourceId: record.payload.resourceId,
+        genesisId: id,
+        head: id,
+        seq: 0n,
+        dataProfile: body.dataProfile,
+        owner: body.owner,
+        route: Object.freeze({ endpoints: body.endpoints, coordinatorUrl: body.coordinatorUrl }),
+        routeVersion: 0n,
+        epoch: Object.freeze({ epoch: dataEpoch(0n), dekCommitment: body.dekCommitment }),
+        epochs: new Map([
+            [
+                "0",
+                Object.freeze({
+                    epoch: dataEpoch(0n),
+                    dekCommitment: body.dekCommitment,
+                    openedBy: id,
+                    closedBy: null,
+                    finalFrontier: null,
+                }),
+            ],
+        ]),
+        grants: new Map(),
+        principals: new Map([[toHex(body.owner.principalId), body.owner]]),
+    });
+}
+/**
+ * The state after a validated record. Applied records (mvpSupported)
+ * change derived state: descriptors (LFCP-020), grants, revocations, claims
+ * and routes (LFCP-021); LFCP-023 adds epochs here. Unapplied (extension)
+ * records move the head and nothing else.
+ */
+function applyRecord(state, record) {
+    const next = { head: controlRecordId(record.signed.id), seq: record.payload.controlSeq };
+    if (!record.mvpSupported)
+        return Object.freeze({ ...state, ...next });
+    const principals = new Map(state.principals);
+    const body = record.body;
+    if (body.type === "CAPABILITY_GRANT")
+        principals.set(toHex(body.subject.principalId), body.subject);
+    if (body.type === "CAPABILITY_CLAIM")
+        principals.set(toHex(body.claimant.principalId), body.claimant);
+    // §23.3 "After commit, the accepting Principal becomes the Resource owner"
+    // (verified by authorizeControlRecord before this record was accepted).
+    const newOwner = transferIssuerDescriptor(record);
+    if (newOwner !== undefined)
+        principals.set(toHex(newOwner.principalId), newOwner);
+    const route = body.type === "ROUTE_UPDATE"
+        ? {
+            route: Object.freeze({ endpoints: body.endpoints, coordinatorUrl: body.coordinatorUrl }),
+            routeVersion: body.routeVersion,
+        }
+        : {};
+    return Object.freeze({
+        ...state,
+        ...next,
+        ...route,
+        ...(body.type === "KEY_EPOCH" ? rotate(state, record, body) : {}),
+        ...(newOwner !== undefined ? { owner: newOwner } : {}),
+        principals,
+        grants: applyCapabilities(state.grants, record),
+    });
+}
+/**
+ * §19: a committed Key Epoch record closes the current epoch with its final
+ * frontier and opens the next one with its DEK commitment. Its succession
+ * (new = current + 1) is checked before it is applied (§19, G-EP3).
+ */
+function rotate(state, record, body) {
+    const id = controlRecordId(record.signed.id);
+    const epochs = new Map(state.epochs);
+    const current = epochs.get(String(state.epoch.epoch));
+    if (current !== undefined)
+        epochs.set(String(current.epoch), Object.freeze({ ...current, closedBy: id, finalFrontier: body.finalFrontier }));
+    epochs.set(String(body.epoch), Object.freeze({
+        epoch: body.epoch,
+        dekCommitment: body.dekCommitment,
+        openedBy: id,
+        closedBy: null,
+        finalFrontier: null,
+    }));
+    return { epoch: Object.freeze({ epoch: body.epoch, dekCommitment: body.dekCommitment }), epochs };
+}
+/**
+ * Validates a set of exact signed Control Records of one Resource, from
+ * Genesis or after `options.start`. Input objects that are already decoded
+ * are re-decoded from their exact bytes, never trusted as decoded.
+ */
+export function validateControlChain(inputs, options = {}) {
+    const entries = [];
+    const early = [];
+    inputs.forEach((input, index) => {
+        const bytes = input instanceof Uint8Array ? input : input.signed.bytes;
+        try {
+            const record = decodeControlRecord(bytes);
+            entries.push({ index, record, key: toHex(record.signed.id) });
+        }
+        catch (e) {
+            const error = e instanceof LfcpError ? e : new LfcpError("INVALID_STRUCTURE", String(e));
+            let recordId = null;
+            try {
+                recordId = controlRecordId(objectId(bytes));
+            }
+            catch {
+                // not bytes at all
+            }
+            early.push(problem(error.code === "UNSUPPORTED_VALUE"
+                ? "UNSUPPORTED_TYPE"
+                : error.code === "INVALID_CONTROL_CHAIN"
+                    ? "SEQUENCE"
+                    : "MALFORMED", { index, recordId, seq: -1n }, error.message, error));
+        }
+    });
+    // DV1 (MVP-0.1-PROTOCOL-SCOPE §4): "An MVP 0.1 implementation MUST refuse
+    // a Control Chain that contains" a COORDINATOR_RECOVERY (7) or a
+    // RESOURCE_TOMBSTONE (8) record, "with PROTOCOL_UNSUPPORTED".
+    for (const e of entries) {
+        const type = e.record.body.type;
+        if (type === "COORDINATOR_RECOVERY" || type === "RESOURCE_TOMBSTONE")
+            early.push(problem("DEFERRED_TYPE", at(e), `a ${type} record: MVP 0.1 refuses a chain containing one (scope §4, DV1)`));
+    }
+    if (early.length > 0)
+        return invalid(early);
+    // The same record delivered twice is one record.
+    const unique = new Map();
+    for (const e of entries)
+        if (!unique.has(e.key))
+            unique.set(e.key, e);
+    const all = [...unique.values()];
+    const geneses = all.filter((e) => e.record.body.type === "GENESIS");
+    let rest = all.filter((e) => e.record.body.type !== "GENESIS");
+    let state;
+    const records = [];
+    const start = options.start;
+    if (start !== undefined) {
+        const others = geneses.filter((g) => g.key !== toHex(start.genesisId));
+        if (others.length > 0) {
+            if (others.some((g) => toHex(g.record.payload.resourceId) !== toHex(start.resourceId)))
+                return invalid(others.map((g) => problem("RESOURCE", at(g), "a Genesis of another Resource")));
+            // §13.2: "Two different validly signed Genesis Records for one Resource
+            // ID are a fork at the root": neither is accepted (CONTROL_CONFLICT).
+            return conflict(null, 0n, [start.genesisId, ...others.map((g) => rid(g.record))], null);
+        }
+        rest = rest.filter((e) => e.key !== toHex(start.head));
+        state = start;
+    }
+    else {
+        if (geneses.length === 0)
+            return invalid([
+                problem("NO_GENESIS", { index: null, recordId: null, seq: -1n }, "the chain has no Genesis record"),
+            ]);
+        const bad = [];
+        for (const g of geneses) {
+            const v = verifyGenesis(g.record);
+            if (!v.valid)
+                bad.push(problem(v.reason === "ISSUER_NOT_OWNER" ? "GENESIS_SIGNER" : "SIGNATURE", at(g), `Genesis is not signed by its owner (${v.reason}, §15)`));
+        }
+        if (bad.length > 0)
+            return invalid(bad);
+        if (geneses.length > 1) {
+            const resource = toHex(geneses[0].record.payload.resourceId);
+            if (geneses.some((g) => toHex(g.record.payload.resourceId) !== resource))
+                return invalid(geneses.map((g) => problem("RESOURCE", at(g), "Genesis records of different Resources")));
+            // §13.2: "Two different validly signed Genesis Records for one Resource
+            // ID are a fork at the root": neither is accepted (CONTROL_CONFLICT).
+            return conflict(null, 0n, geneses.map((g) => rid(g.record)), null);
+        }
+        const genesis = geneses[0];
+        state = genesisState(genesis.record);
+        records.push(genesis.record);
+    }
+    const structural = [];
+    for (const e of rest) {
+        if (toHex(e.record.payload.resourceId) !== toHex(state.resourceId))
+            structural.push(problem("RESOURCE", at(e), "the record belongs to another Resource"));
+        else if (e.record.payload.prevControlId === null)
+            structural.push(problem("PREVIOUS", at(e), "a non-Genesis record without a previous record ID (§13.1)"));
+    }
+    if (structural.length > 0)
+        return invalid(structural);
+    const children = new Map();
+    for (const e of rest) {
+        const prev = toHex(e.record.payload.prevControlId);
+        children.set(prev, [...(children.get(prev) ?? []), e]);
+    }
+    const unapplied = [];
+    const states = new Map([[toHex(state.head), state]]);
+    const visited = new Set();
+    const authorize = options.authorize ?? authorizeControlRecord;
+    for (;;) {
+        const kids = children.get(toHex(state.head)) ?? [];
+        if (kids.length === 0)
+            break;
+        const problems = [];
+        const valid = [];
+        for (const k of kids) {
+            const p = k.record.payload;
+            if (p.controlSeq !== state.seq + 1n) {
+                problems.push(problem("SEQUENCE", at(k), `control_seq ${p.controlSeq} after ${state.seq} (§13.1)`));
+                continue;
+            }
+            // §13: the issuer signs, and kid MUST equal it (see controlRecordSigner).
+            const issuer = controlRecordSigner(k.record);
+            const descriptor = state.principals.get(toHex(issuer)) ??
+                transferIssuerDescriptor(k.record) ??
+                options.resolvePrincipal?.(issuer);
+            if (descriptor === undefined) {
+                problems.push(problem("UNRESOLVED_ISSUER", at(k), "no descriptor is known for the issuer"));
+                continue;
+            }
+            const v = verifySignedObject(k.record.signed, descriptor);
+            if (!v.valid) {
+                problems.push(problem("SIGNATURE", at(k), `the record is not signed by its issuer (${v.reason})`));
+                continue;
+            }
+            // §19: "The new epoch number MUST be exactly the previous Data Epoch plus one."
+            if (k.record.body.type === "KEY_EPOCH" && k.record.body.epoch !== state.epoch.epoch + 1n) {
+                problems.push(problem("EPOCH", at(k), `Key Epoch ${k.record.body.epoch} after epoch ${state.epoch.epoch}: must be the previous epoch plus one (§19)`));
+                continue;
+            }
+            const decision = authorize(k.record, state);
+            if (decision === false || (typeof decision === "object" && !decision.allowed)) {
+                const refusal = typeof decision === "object" && !decision.allowed ? decision : undefined;
+                // §23.3: a transfer offer or acceptance whose signature does not verify.
+                if (refusal?.code === "INVALID_SIGNATURE")
+                    problems.push(problem("SIGNATURE", at(k), refusal.reason));
+                else
+                    problems.push(problem("UNAUTHORIZED", at(k), `the record is not authorized: ${refusal?.reason ?? "refused"}`));
+                continue;
+            }
+            valid.push(k);
+        }
+        if (problems.length > 0)
+            return invalid(problems);
+        if (valid.length > 1)
+            return conflict(state.head, state.seq + 1n, valid.map((k) => rid(k.record)), state);
+        const k = valid[0];
+        visited.add(k.key);
+        records.push(k.record);
+        if (!k.record.mvpSupported)
+            unapplied.push(rid(k.record));
+        state = applyRecord(state, k.record);
+        states.set(toHex(state.head), state);
+    }
+    const unlinked = rest.filter((e) => !visited.has(e.key));
+    if (unlinked.length > 0)
+        return invalid(unlinked.map((e) => problem("PREVIOUS", at(e), "the previous record ID does not name the chain's record at the previous sequence (§13.1)")));
+    return Object.freeze({
+        kind: "linear",
+        state,
+        records: Object.freeze(records),
+        unappliedRecords: Object.freeze(unapplied),
+        stateAt: (head) => states.get(toHex(head)),
+    });
+}
+//# sourceMappingURL=chain.js.map

package/dist/control-sync.d.ts

@@ -0,0 +1,69 @@
+import type { ControlHeadRef } from "./message.js";
+/**
+ * Control Plane anti-entropy planning (LFCP-WIRE-01 §44, §45, §67): from
+ * our Control Head and the heads a peer announces in CONTROL_HAVE (or
+ * RESOURCE_OPENED), decide what to request. Pure; no network loop.
+ *
+ * A fork is surfaced, never resolved: two or more peer heads (§42, §44),
+ * or a peer head at a sequence we hold whose record ID is not ours (§13.2).
+ * The plan then asks for the contested records, so the receiver can
+ * validate them (validateControlChain reports CONTROL_CONFLICT) instead of
+ * choosing a branch.
+ */
+/** What we know of our chain: its head, and the record ID at any sequence we hold. */
+export interface LocalControl {
+    readonly head: ControlHeadRef;
+    readonly recordIdAt: (seq: bigint) => Uint8Array | undefined;
+}
+export type ControlSyncPlan = 
+/** Both sides have the same head. */
+{
+    readonly kind: "in-sync";
+}
+/** G-HV2: an empty CONTROL_HAVE means the peer has no Control Records. */
+ | {
+    readonly kind: "peer-empty";
+}
+/** The peer is ahead on our chain: CONTROL_GET(start..end) (§45, §67). */
+ | {
+    readonly kind: "fetch";
+    readonly start: bigint;
+    readonly end: bigint;
+}
+/** The peer is behind on our chain; it may fetch from us. Nothing to request. */
+ | {
+    readonly kind: "peer-behind";
+    readonly peerSeq: bigint;
+}
+/**
+ * A fork: never resolved here. `fetch` covers the contested sequences
+ * (and anything the peer has beyond them), so every competing record can
+ * be validated.
+ */
+ | {
+    readonly kind: "fork";
+    readonly reason: "PEER_HEADS" | "DIVERGED";
+    readonly heads: readonly ControlHeadRef[];
+    readonly fetch: {
+        readonly start: bigint;
+        readonly end: bigint;
+    };
+};
+/** Plans Control synchronization against a peer's announced heads. `local` is null when we hold no records. */
+export declare function planControlSync(local: LocalControl | null, peerHeads: readonly ControlHeadRef[]): ControlSyncPlan;
+/** The LocalControl of a validated linear chain (records[i] is at sequence i from Genesis). */
+export declare function localControlOf(chain: {
+    readonly state: {
+        readonly head: Uint8Array;
+        readonly seq: bigint;
+    };
+    readonly records: readonly {
+        readonly signed: {
+            readonly id: Uint8Array;
+        };
+        readonly payload: {
+            readonly controlSeq: bigint;
+        };
+    }[];
+}): LocalControl;
+//# sourceMappingURL=control-sync.d.ts.map

package/dist/control-sync.js

@@ -0,0 +1,44 @@
+import { bytesEqual } from "@openlfcp/core";
+/** Plans Control synchronization against a peer's announced heads. `local` is null when we hold no records. */
+export function planControlSync(local, peerHeads) {
+    if (peerHeads.length === 0)
+        return Object.freeze({ kind: "peer-empty" });
+    const maxSeq = peerHeads.reduce((m, h) => (h.seq > m ? h.seq : m), 0n);
+    if (peerHeads.length > 1) {
+        const minSeq = peerHeads.reduce((m, h) => (h.seq < m ? h.seq : m), maxSeq);
+        const ours = local?.head.seq;
+        const start = ours === undefined ? 0n : ours < minSeq ? ours + 1n : minSeq;
+        return Object.freeze({
+            kind: "fork",
+            reason: "PEER_HEADS",
+            heads: Object.freeze([...peerHeads]),
+            fetch: Object.freeze({ start, end: maxSeq }),
+        });
+    }
+    const peer = peerHeads[0];
+    if (local === null)
+        return Object.freeze({ kind: "fetch", start: 0n, end: peer.seq });
+    if (peer.seq <= local.head.seq) {
+        const ours = local.recordIdAt(peer.seq);
+        if (ours === undefined || !bytesEqual(ours, peer.recordId))
+            return Object.freeze({
+                kind: "fork",
+                reason: "DIVERGED",
+                heads: Object.freeze([peer]),
+                fetch: Object.freeze({ start: peer.seq, end: peer.seq }),
+            });
+        return peer.seq === local.head.seq
+            ? Object.freeze({ kind: "in-sync" })
+            : Object.freeze({ kind: "peer-behind", peerSeq: peer.seq });
+    }
+    return Object.freeze({ kind: "fetch", start: local.head.seq + 1n, end: peer.seq });
+}
+/** The LocalControl of a validated linear chain (records[i] is at sequence i from Genesis). */
+export function localControlOf(chain) {
+    const byseq = new Map(chain.records.map((r) => [r.payload.controlSeq, r.signed.id]));
+    return Object.freeze({
+        head: Object.freeze({ seq: chain.state.seq, recordId: chain.state.head }),
+        recordIdAt: (seq) => byseq.get(seq),
+    });
+}
+//# sourceMappingURL=control-sync.js.map

package/dist/control.d.ts

@@ -0,0 +1,173 @@
+import { type ControlRecordId, type DataEpoch, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type CborValue } from "./cbor/index.js";
+import { type SignedBytes, type Signer, type VerifyResult } from "./cose.js";
+import { type Endpoint } from "./endpoint.js";
+import { type ActorHave } from "./have.js";
+import { type ControlRecordPayload, type Parsed } from "./objects.js";
+import { type PrincipalDescriptor } from "./principal.js";
+/**
+ * Typed Control Record bodies (LFCP-WIRE-01 §13-§24) and the Control
+ * Record codec on top of the generic envelope (objects.ts, LFCP-016) and
+ * canonical COSE_Sign1 (cose.ts, LFCP-015).
+ *
+ * Structure only: every body is a closed map with its CDDL field types.
+ * Authority, chain linkage, claim limits, epoch succession and route
+ * version monotonicity belong to LFCP-020 to LFCP-023. Decoding never
+ * applies a record; `mvpSupported` tells those layers whether MVP 0.1
+ * implements the type (.github docs/MVP-0.1-PROTOCOL-SCOPE.md §4 defers
+ * coordinator recovery and Resource tombstones; ownership transfer is
+ * verified and applied, its UI/flow deferred).
+ *
+ * Writers apply rules the prose states for creators but not as receiver
+ * checks: wss:// URLs (loopback ws:// allowed), no reserved endpoint flag
+ * bits, at most 256 UTF-8 bytes of reason or note text (writer-side, §22,
+ * §24), a non-empty ability list, and the Genesis invariants. Receivers
+ * check structure, and that every endpoint and coordinator URL is ws or
+ * wss (§16).
+ */
+export type ControlBody = {
+    readonly type: "GENESIS";
+    readonly dataProfile: string;
+    readonly owner: PrincipalDescriptor;
+    readonly dekCommitment: Hash32;
+    readonly endpoints: readonly Endpoint[];
+    readonly coordinatorUrl: string;
+} | {
+    readonly type: "CAPABILITY_GRANT";
+    readonly subject: PrincipalDescriptor;
+    readonly abilities: readonly bigint[];
+    readonly delegable: readonly bigint[];
+    readonly parentGrantId?: ControlRecordId;
+    readonly claimLimit?: bigint;
+} | {
+    readonly type: "CAPABILITY_REVOKE";
+    readonly grantId: ControlRecordId;
+} | {
+    readonly type: "CAPABILITY_CLAIM";
+    readonly invitationGrantId: ControlRecordId;
+    readonly claimant: PrincipalDescriptor;
+    readonly abilities: readonly bigint[];
+} | {
+    readonly type: "KEY_EPOCH";
+    readonly epoch: DataEpoch;
+    readonly dekCommitment: Hash32;
+    /** Accepted final frontier of the previous epoch: canonical entries, one per Principal. */
+    readonly finalFrontier: readonly ActorHave[];
+    readonly reason: bigint;
+} | {
+    readonly type: "ROUTE_UPDATE";
+    readonly routeVersion: bigint;
+    readonly endpoints: readonly Endpoint[];
+    readonly coordinatorUrl: string;
+} | {
+    readonly type: "OWNER_TRANSFER_COMMIT";
+    /** Exact COSE bytes of the transfer offer and accept (§23.3); see parseOwnerTransferOffer/Accept. */
+    readonly offer: Uint8Array;
+    readonly accept: Uint8Array;
+} | {
+    readonly type: "COORDINATOR_RECOVERY";
+    readonly routeVersion: bigint;
+    readonly endpoints: readonly Endpoint[];
+    readonly coordinatorUrl: string;
+    readonly reason: string;
+} | {
+    readonly type: "RESOURCE_TOMBSTONE";
+    readonly reason: bigint;
+    readonly note?: string;
+}
+/** A §14 extension type (32 and up): kept, never interpreted. */
+ | {
+    readonly type: "EXTENSION";
+    readonly code: bigint;
+    readonly body: CborValue;
+};
+export type ControlBodyType = ControlBody["type"];
+/** Whether MVP 0.1 implements a body type (false for deferred core types and extensions). */
+export declare const isMvpSupported: (type: ControlBodyType) => boolean;
+/** The §14 code of a body. */
+export declare const controlTypeOf: (body: ControlBody) => bigint;
+/**
+ * Decodes the body of a Control Record of §14 type `type`. Core types 0-8
+ * get their closed-map structure; 9-31 are UNSUPPORTED_VALUE (§14:
+ * INVALID_CONTROL_CHAIN on the wire); 32 and up are kept as opaque
+ * EXTENSION bodies.
+ */
+export declare function controlBodyFromCbor(type: bigint, value: CborValue): ControlBody;
+/** A received Control Record: the exact object, its envelope and its typed body. Nothing is applied. */
+export interface ControlRecord extends Parsed<ControlRecordPayload> {
+    readonly body: ControlBody;
+    /** False for MVP-deferred core types and extensions: LFCP-020/021 must not apply them. */
+    readonly mvpSupported: boolean;
+}
+/**
+ * Parses a received Control Record: canonical COSE and the generic
+ * envelope (parseControlRecord), then the typed body. The record ID is
+ * `signed.id`, SHA-256 of the exact received bytes. The signature is not
+ * checked here; see controlRecordSigner and verifyGenesis.
+ */
+export declare function decodeControlRecord(bytes: Uint8Array): ControlRecord;
+/**
+ * The Principal whose key must have signed a Control Record: its issuer
+ * (payload field 4). §13: "the protected-header kid MUST equal field 4,
+ * and a record whose kid is any other Principal is rejected with
+ * INVALID_SIGNATURE." Resolving the issuer to a descriptor (and checking
+ * its authority) is LFCP-020/021.
+ */
+export declare const controlRecordSigner: (record: Parsed<ControlRecordPayload>) => PrincipalId;
+/**
+ * Verifies a Genesis record against the owner in its own body (§15:
+ * "MUST be signed by the owner Principal contained in the body"): the
+ * issuer and the kid must be the owner and the signature must verify with
+ * the owner's key. A failure surfaces as INVALID_SIGNATURE.
+ */
+export declare function verifyGenesis(record: ControlRecord): VerifyResult | {
+    readonly valid: false;
+    readonly reason: "NOT_GENESIS" | "ISSUER_NOT_OWNER";
+};
+/** The CBOR of a typed body, applying the writer rules. */
+export declare function controlBodyToCbor(body: ControlBody): CborValue;
+/** The envelope fields a writer chooses; the type comes from the body and the issuer from the signer. */
+export interface ControlRecordHeader {
+    readonly resourceId: ResourceId;
+    readonly controlSeq: bigint;
+    readonly prevControlId: ControlRecordId | null;
+}
+/**
+ * Deterministic CBOR of control-record-payload (§13) for `issuer`. Writer
+ * rules: Genesis is at control_seq 0 with a null link and is issued by the
+ * owner in its body; every other record has control_seq >= 1 and a link
+ * (§13.1). The result is checked with the receiver's decoder too.
+ */
+export declare function encodeControlRecordPayload(header: ControlRecordHeader, issuer: PrincipalId, body: ControlBody): Uint8Array;
+/** A newly signed Control Record: its exact bytes and its ID, SHA-256 of those bytes (§13, §10.6). */
+export interface SignedControlRecord extends SignedBytes {
+    readonly recordId: ControlRecordId;
+}
+/**
+ * Signs a Control Record: typed payload -> deterministic CBOR -> canonical
+ * untagged COSE_Sign1 (signObject) -> exact bytes -> SHA-256 = record ID.
+ * The issuer is the signer's Principal (§13: kid = issuer, see
+ * controlRecordSigner).
+ */
+export declare function signControlRecord(header: ControlRecordHeader, body: ControlBody, signer: Signer): SignedControlRecord;
+export interface OwnerTransferOfferPayload {
+    readonly resourceId: ResourceId;
+    readonly controlHead: ControlRecordId;
+    readonly expectedControlSeq: bigint;
+    readonly proposedOwner: PrincipalDescriptor;
+    readonly nonce: Uint8Array;
+}
+export interface OwnerTransferAcceptPayload {
+    readonly resourceId: ResourceId;
+    readonly offerId: Hash32;
+    readonly newOwner: PrincipalId;
+}
+/** owner-transfer-offer-payload (§23.1). */
+export declare function ownerTransferOfferPayloadFromCbor(value: CborValue): OwnerTransferOfferPayload;
+/** owner-transfer-accept-payload (§23.2). */
+export declare function ownerTransferAcceptPayloadFromCbor(value: CborValue): OwnerTransferAcceptPayload;
+/** Parses a received transfer offer (canonical COSE, typed payload). Deferred from MVP 0.1: never applied. */
+export declare function parseOwnerTransferOffer(bytes: Uint8Array): Parsed<OwnerTransferOfferPayload>;
+/** Parses a received transfer accept (canonical COSE, typed payload). Deferred from MVP 0.1: never applied. */
+export declare function parseOwnerTransferAccept(bytes: Uint8Array): Parsed<OwnerTransferAcceptPayload>;
+//# sourceMappingURL=control.d.ts.map