@openlfcp/wire 0.1.0-rc.1

package/dist/cbor/encode.js

@@ -0,0 +1,149 @@
+import { LfcpError } from "@openlfcp/core";
+import { strictUtf8Decoder, utf8Encoder } from "./text.js";
+import { isCborKey, isCborMap, MAX_DEPTH, UINT64_MAX } from "./value.js";
+/** Byte order of encoded map keys (§5.2 rule 4): shorter encodings first, then bytewise. */
+export function compareEncodedKeys(a, b) {
+    if (a.length !== b.length)
+        return a.length - b.length;
+    for (let i = 0; i < a.length; i += 1) {
+        const d = a[i] - b[i];
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+class Writer {
+    buf = new Uint8Array(256);
+    len = 0;
+    reserve(n) {
+        if (this.len + n <= this.buf.length)
+            return;
+        let size = this.buf.length * 2;
+        while (size < this.len + n)
+            size *= 2;
+        const next = new Uint8Array(size);
+        next.set(this.buf.subarray(0, this.len));
+        this.buf = next;
+    }
+    byte(b) {
+        this.reserve(1);
+        this.buf[this.len++] = b;
+    }
+    bytes(b) {
+        this.reserve(b.length);
+        this.buf.set(b, this.len);
+        this.len += b.length;
+    }
+    /** Major type and argument in the shortest form (§5.2 rule 1). */
+    head(major, n) {
+        const m = major << 5;
+        const v = BigInt(n);
+        if (v < 24n) {
+            this.byte(m | Number(v));
+        }
+        else if (v <= 0xffn) {
+            this.byte(m | 24);
+            this.byte(Number(v));
+        }
+        else if (v <= 0xffffn) {
+            this.byte(m | 25);
+            this.bigEndian(v, 2);
+        }
+        else if (v <= 0xffffffffn) {
+            this.byte(m | 26);
+            this.bigEndian(v, 4);
+        }
+        else {
+            this.byte(m | 27);
+            this.bigEndian(v, 8);
+        }
+    }
+    bigEndian(v, size) {
+        for (let i = size - 1; i >= 0; i -= 1)
+            this.byte(Number((v >> BigInt(8 * i)) & 0xffn));
+    }
+    result() {
+        return this.buf.slice(0, this.len);
+    }
+}
+function writeInteger(w, value) {
+    if (typeof value === "number" && !Number.isSafeInteger(value)) {
+        throw new LfcpError(Number.isInteger(value) ? "CBOR_OUT_OF_RANGE" : "CBOR_UNSUPPORTED_TYPE", Number.isInteger(value)
+            ? "integers beyond the safe range must be bigint"
+            : "floating-point numbers are not used by LFCP");
+    }
+    const v = BigInt(value);
+    if (v > UINT64_MAX || v < -(UINT64_MAX + 1n))
+        throw new LfcpError("CBOR_OUT_OF_RANGE", "integer outside -2^64 .. 2^64-1");
+    if (v >= 0n)
+        w.head(0, v);
+    else
+        w.head(1, -1n - v);
+}
+function writeValue(w, value, depth) {
+    if (depth > MAX_DEPTH)
+        throw new LfcpError("CBOR_TOO_DEEP", `nesting deeper than ${MAX_DEPTH}`);
+    if (value === null) {
+        w.byte(0xf6);
+        return;
+    }
+    if (typeof value === "boolean") {
+        w.byte(value ? 0xf5 : 0xf4);
+        return;
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+        writeInteger(w, value);
+        return;
+    }
+    if (value instanceof Uint8Array) {
+        w.head(2, value.length);
+        w.bytes(value);
+        return;
+    }
+    if (typeof value === "string") {
+        const raw = utf8Encoder.encode(value);
+        // TextEncoder replaces lone surrogates; refuse instead of changing the text.
+        if (strictUtf8Decoder.decode(raw) !== value)
+            throw new LfcpError("CBOR_INVALID_UTF8", "string contains lone surrogates");
+        w.head(3, raw.length);
+        w.bytes(raw);
+        return;
+    }
+    if (Array.isArray(value)) {
+        w.head(4, value.length);
+        for (const item of value)
+            writeValue(w, item, depth + 1);
+        return;
+    }
+    if (isCborMap(value)) {
+        const encoded = value.entries.map(([k, v]) => {
+            if (!isCborKey(k))
+                throw new LfcpError("CBOR_UNSUPPORTED_TYPE", "map keys must be integers, text or byte strings");
+            return [encode(k), v];
+        });
+        encoded.sort((a, b) => compareEncodedKeys(a[0], b[0]));
+        for (let i = 1; i < encoded.length; i += 1) {
+            if (compareEncodedKeys(encoded[i - 1][0], encoded[i][0]) === 0) {
+                throw new LfcpError("CBOR_DUPLICATE_KEY", "map contains a duplicate key");
+            }
+        }
+        w.head(5, encoded.length);
+        for (const [k, v] of encoded) {
+            w.bytes(k);
+            writeValue(w, v, depth + 1);
+        }
+        return;
+    }
+    throw new LfcpError("CBOR_UNSUPPORTED_TYPE", `cannot encode ${typeof value} as LFCP CBOR`);
+}
+/**
+ * Deterministic CBOR encoding (LFCP-WIRE-01 §5.2): shortest heads,
+ * definite lengths, map keys sorted by encoded length then bytewise,
+ * duplicate keys rejected, array order kept, no tags.
+ */
+export function encode(value) {
+    const w = new Writer();
+    writeValue(w, value, 0);
+    return w.result();
+}
+//# sourceMappingURL=encode.js.map

package/dist/cbor/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Low-level deterministic CBOR for LFCP-WIRE-01 §5.2.
+ *
+ * This is a building block for COSE, Wire structures and vectors; it is not
+ * the LFCP API. Import it from `@openlfcp/wire/cbor`.
+ */
+export { decodeDeterministic, decodeStrict, isDeterministic } from "./decode.js";
+export { compareEncodedKeys, encode } from "./encode.js";
+export { type CborKey, type CborMap, type CborValue, cborMap, isCborMap, MAX_DEPTH, } from "./value.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cbor/index.js

@@ -0,0 +1,10 @@
+/**
+ * Low-level deterministic CBOR for LFCP-WIRE-01 §5.2.
+ *
+ * This is a building block for COSE, Wire structures and vectors; it is not
+ * the LFCP API. Import it from `@openlfcp/wire/cbor`.
+ */
+export { decodeDeterministic, decodeStrict, isDeterministic } from "./decode.js";
+export { compareEncodedKeys, encode } from "./encode.js";
+export { cborMap, isCborMap, MAX_DEPTH, } from "./value.js";
+//# sourceMappingURL=index.js.map

package/dist/cbor/text.d.ts

@@ -0,0 +1,11 @@
+interface Utf8Encoder {
+    encode(text: string): Uint8Array;
+}
+interface Utf8Decoder {
+    decode(bytes: Uint8Array): string;
+}
+export declare const utf8Encoder: Utf8Encoder;
+/** Throws on malformed UTF-8 instead of inserting U+FFFD. */
+export declare const strictUtf8Decoder: Utf8Decoder;
+export {};
+//# sourceMappingURL=text.d.ts.map

package/dist/cbor/text.js

@@ -0,0 +1,5 @@
+const g = globalThis;
+export const utf8Encoder = new g.TextEncoder();
+/** Throws on malformed UTF-8 instead of inserting U+FFFD. */
+export const strictUtf8Decoder = new g.TextDecoder("utf-8", { fatal: true });
+//# sourceMappingURL=text.js.map

package/dist/cbor/value.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The CBOR data model LFCP uses (LFCP-WIRE-01 §5). Everything else is
+ * unrepresentable here and rejected by the decoder:
+ *
+ * - integers (major types 0 and 1, §5.1): `number` when it is a safe
+ *   integer, `bigint` otherwise, in -2^64 .. 2^64-1;
+ * - byte strings: `Uint8Array`; text strings: `string` (well-formed UTF-8);
+ * - arrays: `CborValue[]`, order preserved (§5.2 rule 5);
+ * - maps: `CborMap`, an explicit entry list, never a JS object (§5.2 rule 4);
+ * - `true`, `false`, `null`.
+ *
+ * No tags (§5.2 rule 6: LFCP requires none in deterministic structures), no
+ * floating-point numbers, no `undefined`, no other simple values.
+ */
+export type CborValue = CborKey | boolean | null | readonly CborValue[] | CborMap;
+/** Map keys: integers, text strings and byte strings. */
+export type CborKey = number | bigint | string | Uint8Array;
+/** A CBOR map. Entry order is irrelevant on input; encoding sorts the keys. */
+export interface CborMap {
+    readonly kind: "cbor-map";
+    readonly entries: readonly (readonly [CborKey, CborValue])[];
+}
+export declare function isCborMap(value: unknown): value is CborMap;
+export declare function isCborKey(value: unknown): value is CborKey;
+/** Builds a map from `[key, value]` pairs. Duplicate keys are rejected when encoding. */
+export declare function cborMap(entries: Iterable<readonly [CborKey, CborValue]>): CborMap;
+/** Largest nesting depth accepted when encoding or decoding; an SDK safety limit, not a protocol rule. */
+export declare const MAX_DEPTH = 128;
+export declare const UINT64_MAX: bigint;
+//# sourceMappingURL=value.d.ts.map

package/dist/cbor/value.js

@@ -0,0 +1,23 @@
+import { LfcpError } from "@openlfcp/core";
+export function isCborMap(value) {
+    return (typeof value === "object" && value !== null && value.kind === "cbor-map");
+}
+export function isCborKey(value) {
+    return (typeof value === "number" ||
+        typeof value === "bigint" ||
+        typeof value === "string" ||
+        value instanceof Uint8Array);
+}
+/** Builds a map from `[key, value]` pairs. Duplicate keys are rejected when encoding. */
+export function cborMap(entries) {
+    const list = [...entries].map(([k, v]) => {
+        if (!isCborKey(k))
+            throw new LfcpError("CBOR_UNSUPPORTED_TYPE", "map keys must be integers, text or byte strings");
+        return [k, v];
+    });
+    return Object.freeze({ kind: "cbor-map", entries: Object.freeze(list) });
+}
+/** Largest nesting depth accepted when encoding or decoding; an SDK safety limit, not a protocol rule. */
+export const MAX_DEPTH = 128;
+export const UINT64_MAX = (1n << 64n) - 1n;
+//# sourceMappingURL=value.js.map

package/dist/chain.d.ts

@@ -0,0 +1,140 @@
+import { type ControlRecordId, type DataEpoch, type Hash32, LfcpError, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type Authorization, type Grant } from "./capability.js";
+import { type ControlRecord } from "./control.js";
+import type { Endpoint } from "./endpoint.js";
+import type { ActorHave } from "./have.js";
+import type { PrincipalDescriptor } from "./principal.js";
+/**
+ * Control Chain validation (LFCP-WIRE-01 §13, §13.1, §13.2, §15).
+ *
+ * A pure function over exact signed Control Records: no I/O, clock or
+ * randomness. The records may arrive in any order; the chain is ordered by
+ * its own links (prev_control_id from Genesis), so every permutation of a
+ * set gives the same result. Diagnostics are sorted by sequence and then
+ * record ID only to make them reproducible; nothing ever chooses a branch.
+ *
+ * A fork (two validly signed records naming the same previous record) is a
+ * conflict, never resolved by time, ID order, arrival order or server
+ * preference (§13.2). A chain containing a Coordinator Recovery (7) or
+ * Resource Tombstone (8) record is refused with PROTOCOL_UNSUPPORTED
+ * (MVP-0.1-PROTOCOL-SCOPE §4, DV1). Extension records (32 and above) need
+ * owner authority (§14) and stay in the chain, since the links run through
+ * them, but are not applied to the derived state; they are listed in
+ * `unappliedRecords`.
+ */
+/** The initial and current route (§15, §20). */
+export interface ControlRoute {
+    readonly endpoints: readonly Endpoint[];
+    readonly coordinatorUrl: string;
+}
+/** A Data Epoch and its DEK commitment (§11, §15, §19). */
+export interface ControlEpoch {
+    readonly epoch: DataEpoch;
+    readonly dekCommitment: Hash32;
+}
+/**
+ * One Data Epoch in the chain's history (§11, §15, §19): opened by Genesis
+ * (epoch 0) or a Key Epoch record, and closed by the next Key Epoch record,
+ * which records its final frontier (§19.1). Kept for every epoch, so units
+ * of any older epoch stay evaluable.
+ */
+export interface EpochHistory extends ControlEpoch {
+    readonly openedBy: ControlRecordId;
+    /** The Key Epoch record that closed this epoch, or null while it is current. */
+    readonly closedBy: ControlRecordId | null;
+    /** The accepted final frontier of this epoch (canonical, G-CP1), or null while it is current. */
+    readonly finalFrontier: readonly ActorHave[] | null;
+}
+/**
+ * The validated state of one Resource's Control Chain. This is the single
+ * Control state type: LFCP-021 (capabilities) and LFCP-023 (epochs and
+ * cutoff) extend it here and in `applyRecord`, never with a parallel type.
+ *
+ * LFCP-020 fills the chain position and what Genesis establishes;
+ * LFCP-021 adds the grants and applies route updates; LFCP-023 applies
+ * Key Epoch rotation (`epoch`, `epochs`).
+ */
+export interface ControlState {
+    readonly resourceId: ResourceId;
+    readonly genesisId: ControlRecordId;
+    /** The current Control Head: the record ID of the last validated record. */
+    readonly head: ControlRecordId;
+    readonly seq: bigint;
+    readonly dataProfile: string;
+    /** The owner: the Genesis owner, or the new owner after a verified transfer (§15, §23.3). */
+    readonly owner: PrincipalDescriptor;
+    readonly route: ControlRoute;
+    /** §20 route version of `route`; Genesis implies route version 0 (§15). */
+    readonly routeVersion: bigint;
+    /** The current Data Epoch. */
+    readonly epoch: ControlEpoch;
+    /** Every Data Epoch so far, by epoch number (decimal string) (§19, LFCP-023). */
+    readonly epochs: ReadonlyMap<string, EpochHistory>;
+    /** Grants created through this head (§17.2, §18.1), by grant ID hex; see capability.ts. */
+    readonly grants: ReadonlyMap<string, Grant>;
+    /**
+     * Principal Descriptors carried by applied records (Genesis owner, grant
+     * subjects, claimants), by Principal ID hex. Descriptors are
+     * self-certifying (§7), so knowing one grants nothing; it only lets later
+     * records by that Principal be verified.
+     */
+    readonly principals: ReadonlyMap<string, PrincipalDescriptor>;
+}
+/** Why a chain is invalid. */
+export type ChainProblem = "MALFORMED" | "UNSUPPORTED_TYPE" | "NO_GENESIS" | "GENESIS_SIGNER" | "RESOURCE" | "SEQUENCE" | "PREVIOUS" | "SIGNATURE" | "UNRESOLVED_ISSUER" | "EPOCH" | "UNAUTHORIZED" | "DEFERRED_TYPE";
+export type ChainResult = {
+    readonly kind: "linear";
+    readonly state: ControlState;
+    /** The validated records in chain order (from the start, Genesis included when no start was given). */
+    readonly records: readonly ControlRecord[];
+    /** Extension records kept in the chain but not applied (mvpSupported = false), in chain order. */
+    readonly unappliedRecords: readonly ControlRecordId[];
+    /**
+     * The validated state at any head of this chain (from the start, or
+     * Genesis), for evaluating authority at an older Control Head. States
+     * are kept by immutable head ID; undefined for a head not on the chain.
+     */
+    readonly stateAt: (head: Uint8Array) => ControlState | undefined;
+} | {
+    readonly kind: "conflict";
+    readonly wireCode: "CONTROL_CONFLICT";
+    /** The record both branches name as previous; null when two Genesis records compete. */
+    readonly commonHead: ControlRecordId | null;
+    /** The contested sequence. */
+    readonly seq: bigint;
+    /** The competing record IDs, sorted by bytes for reproducible output (not a ranking). */
+    readonly competing: readonly ControlRecordId[];
+    /** The validated common prefix up to commonHead (null for a Genesis conflict); no branch is applied. */
+    readonly prefixState: ControlState | null;
+} | {
+    readonly kind: "invalid";
+    readonly problem: ChainProblem;
+    readonly wireCode: string;
+    /** Position in the input array of the offending record (null when no record is at fault). */
+    readonly index: number | null;
+    readonly recordId: ControlRecordId | null;
+    readonly error: LfcpError;
+};
+export interface ChainOptions {
+    /** Continue after an already validated head instead of starting from Genesis. */
+    readonly start?: ControlState;
+    /**
+     * Resolves an issuer that no earlier record in the chain describes.
+     * The returned descriptor is checked against the ID like any other.
+     */
+    readonly resolvePrincipal?: (id: PrincipalId) => PrincipalDescriptor | undefined;
+    /**
+     * Authorization, called for every non-Genesis record with the state
+     * before it (the previous head). Defaults to authorizeControlRecord, the
+     * LFCP-021 capability engine; a caller may substitute a policy (tests).
+     * A refusal makes the chain invalid (UNAUTHORIZED).
+     */
+    readonly authorize?: (record: ControlRecord, state: ControlState) => boolean | Authorization;
+}
+/**
+ * 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 declare function validateControlChain(inputs: readonly (Uint8Array | ControlRecord)[], options?: ChainOptions): ChainResult;
+//# sourceMappingURL=chain.d.ts.map