@openlfcp/wire 0.1.0-rc.1

package/dist/snapshot.js

@@ -0,0 +1,189 @@
+import { bytesEqual, compareCanonicalFrontierOrder, dataEpoch, hash32, LfcpError, toHex, } from "@openlfcp/core";
+import { decryptSnapshot, dekCommitment, deriveSnapshotKey, encryptSnapshot, } from "@openlfcp/crypto";
+import { ABILITY, hasAbility } from "./capability.js";
+import { cborMap, decodeStrict, encode } from "./cbor/index.js";
+import { signObject, verifySignedObject } from "./cose.js";
+import { canonicalFrontierToCbor, missingFrom } from "./have.js";
+import { parseSnapshot, snapshotPayloadFromCbor, } from "./objects.js";
+/**
+ * Encrypted, signed Snapshots (LFCP-WIRE-01 §29, §29.1, §29.2): a
+ * materialization of profile state at a canonical Data frontier. The
+ * plaintext is opaque here; its framing belongs to the Data Profile.
+ *
+ * Creation: canonical frontier → Snapshot key (§29.1.1) → nonce from the
+ * Snapshot Sequence (§29.1.2) → the exact seven-element AAD (§29.1.3) →
+ * ChaCha20-Poly1305 (§29.1.4) → deterministic payload → COSE_Sign1 by the
+ * publisher → exact bytes → SHA-256 = Snapshot ID. The public creation API
+ * is createSnapshot (@openlfcp/client), which takes the sequence from a
+ * SnapshotSequenceReservation; sealSnapshot is its building block.
+ *
+ * Receipt (checkSnapshot without a DEK, receiveSnapshot with one):
+ *  1. structure: canonical COSE_Sign1, deterministic payload, Snapshot
+ *     Sequence ≥ 1 and a canonical frontier, as received (never
+ *     re-normalized) → MALFORMED_MESSAGE;
+ *  2. the Resource is the chain's → MALFORMED_MESSAGE;
+ *  3. the publisher resolves to a descriptor → MISSING_DEPENDENCY;
+ *  4. kid = publisher and a strict signature → INVALID_SIGNATURE;
+ *  5. the Control Head is on the valid chain → MISSING_DEPENDENCY;
+ *  6. the publisher held snapshot/publish at that head (§29.2) →
+ *     AUTHORIZATION_FAILED;
+ *  7. the epoch is known at that head → MISSING_DEPENDENCY;
+ *  8. when the epoch has since been closed, the frontier covers no unit
+ *     beyond its final frontier → STALE_DATA_EPOCH (§29, G-EP4);
+ *  9. the DEK, the exact AAD rebuilt from the received fields, AEAD
+ *     (one layout only, §29.1.4) → client-local failure, no wire code;
+ * 10. the Data Profile's Snapshot codec accepts the plaintext.
+ */
+const SNAPSHOT_LABEL = "LFCP-SNAPSHOT-v1";
+/**
+ * §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 function snapshotAad(fields) {
+    if (fields.snapshotSeq < 1n)
+        throw new LfcpError("OUT_OF_RANGE", "a Snapshot Sequence starts at 1 (§29)");
+    return encode([
+        SNAPSHOT_LABEL,
+        fields.resourceId,
+        dataEpoch(fields.dataEpoch),
+        fields.publisher,
+        fields.snapshotSeq,
+        fields.controlHead,
+        canonicalFrontierExact(fields.frontier),
+    ]);
+}
+/**
+ * The frontier's canonical CBOR (§28.1, §28.2). The frontier must already
+ * be canonical: entries in strictly ascending raw Principal ID order (one
+ * per actor) and each entry canonical. It is never re-ordered.
+ */
+function canonicalFrontierExact(frontier) {
+    for (let i = 1; i < frontier.length; i++)
+        if (compareCanonicalFrontierOrder(frontier[i - 1].principalId, frontier[i].principalId) >= 0)
+            throw new LfcpError("INVALID_STRUCTURE", "the frontier must be sorted by raw Principal ID with one entry per actor (§28.2)");
+    return canonicalFrontierToCbor(frontier);
+}
+/** The deterministic §29 payload, keys 0-6; checked by the receiver rules before it is returned. */
+export function encodeSnapshotPayload(fields) {
+    const bytes = encode(cborMap([
+        [0, fields.resourceId],
+        [1, dataEpoch(fields.dataEpoch)],
+        [2, fields.publisher],
+        [3, fields.snapshotSeq],
+        [4, fields.controlHead],
+        [5, canonicalFrontierExact(fields.frontier)],
+        [6, fields.ciphertext],
+    ]));
+    snapshotPayloadFromCbor(decodeStrict(bytes));
+    return bytes;
+}
+/**
+ * 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 function sealSnapshot(fields, plaintext, dek, publisher) {
+    const full = { ...fields, publisher: publisher.descriptor.principalId };
+    const key = deriveSnapshotKey(dek, full.resourceId, full.dataEpoch, full.publisher);
+    const ciphertext = encryptSnapshot(key, full.snapshotSeq, snapshotAad(full), plaintext);
+    const signed = signObject(encodeSnapshotPayload({ ...full, ciphertext }), publisher);
+    return Object.freeze({ bytes: signed.bytes, snapshotId: hash32(signed.id) });
+}
+const rejected = (reason, wireCode, message) => Object.freeze({ kind: "rejected", reason, wireCode, message });
+/** Steps 1-8: everything that needs no DEK, for servers and clients. */
+export function checkSnapshot(view, bytes, options = {}) {
+    let parsed;
+    try {
+        parsed = parseSnapshot(bytes);
+    }
+    catch (e) {
+        return rejected("MALFORMED", "MALFORMED_MESSAGE", e instanceof Error ? e.message : String(e));
+    }
+    const p = parsed.payload;
+    if (!bytesEqual(p.resourceId, view.state.resourceId))
+        return rejected("OTHER_RESOURCE", "MALFORMED_MESSAGE", "the Snapshot is for another Resource");
+    const publisher = view.state.principals.get(toHex(p.publisher)) ?? options.resolvePrincipal?.(p.publisher);
+    if (publisher === undefined || !bytesEqual(publisher.principalId, p.publisher))
+        return rejected("UNKNOWN_PUBLISHER", "MISSING_DEPENDENCY", "no Principal Descriptor is known for the publisher");
+    const signature = verifySignedObject(parsed.signed, publisher);
+    if (!signature.valid)
+        return rejected("SIGNATURE", "INVALID_SIGNATURE", `the Snapshot is not signed by its publisher (${signature.reason})`);
+    const atHead = view.stateAt(p.controlHead);
+    if (atHead === undefined)
+        return rejected("UNKNOWN_CONTROL_HEAD", "MISSING_DEPENDENCY", `Control Head ${toHex(p.controlHead)} is not on the chain`);
+    if (!hasAbility(atHead, p.publisher, ABILITY.SNAPSHOT_PUBLISH))
+        return rejected("UNAUTHORIZED", "AUTHORIZATION_FAILED", "the publisher did not hold snapshot/publish at the referenced Control Head (§29.2)");
+    if (!atHead.epochs.has(String(p.dataEpoch)))
+        return rejected("UNKNOWN_EPOCH", "MISSING_DEPENDENCY", `epoch ${p.dataEpoch} is not known at the referenced Control Head`);
+    const beyond = beyondCutoff(view, p.dataEpoch, p.frontier);
+    if (beyond !== undefined)
+        return rejected("BEYOND_CUTOFF", "STALE_DATA_EPOCH", beyond);
+    return Object.freeze({ kind: "valid", parsed, snapshotId: hash32(parsed.signed.id) });
+}
+/**
+ * §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 function beyondCutoff(view, epoch, frontier) {
+    const history = view.state.epochs.get(String(epoch));
+    if (history?.finalFrontier === null || history?.finalFrontier === undefined)
+        return undefined;
+    const extra = missingFrom(history.finalFrontier, frontier);
+    if (extra.length === 0)
+        return undefined;
+    const first = extra[0];
+    return `the frontier covers units beyond epoch ${epoch}'s final frontier (actor ${toHex(first.actor).slice(0, 16)}… ${first.start}..${first.end}; G-EP4)`;
+}
+/** A received Snapshot end to end (steps 1-10). Only "accepted" may be loaded. */
+export async function receiveSnapshot(view, bytes, options) {
+    if (options.profile.dataProfile !== view.state.dataProfile)
+        throw new LfcpError("DATA_PROFILE_MISMATCH", `the profile codec is for ${options.profile.dataProfile}, the Resource uses ${view.state.dataProfile}`);
+    const c = checkSnapshot(view, bytes, options);
+    if (c.kind !== "valid")
+        return c;
+    const p = c.parsed.payload;
+    const local = (reason, message) => Object.freeze({ kind: "local-failure", reason, snapshotId: c.snapshotId, message });
+    const dek = await options.dek(p.dataEpoch);
+    if (dek === undefined)
+        return local("NO_DEK", `no DEK is held for epoch ${p.dataEpoch}`);
+    const commitment = view.state.epochs.get(String(p.dataEpoch))?.dekCommitment;
+    if (commitment === undefined ||
+        !bytesEqual(dekCommitment(p.resourceId, p.dataEpoch, dek), commitment))
+        return local("DEK_COMMITMENT_MISMATCH", "the DEK does not match the epoch's commitment");
+    let plaintext;
+    try {
+        const key = deriveSnapshotKey(dek, p.resourceId, p.dataEpoch, p.publisher);
+        plaintext = decryptSnapshot(key, p.snapshotSeq, snapshotAad(p), p.ciphertext);
+    }
+    catch (e) {
+        if (e instanceof LfcpError && e.code === "AEAD_AUTHENTICATION_FAILED")
+            return local("AEAD", e.message);
+        throw e;
+    }
+    let value;
+    try {
+        value = options.profile.decode(plaintext);
+    }
+    catch (e) {
+        return local("PROFILE_REJECTED", `the Data Profile rejects the Snapshot plaintext: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return Object.freeze({
+        kind: "accepted",
+        snapshotId: c.snapshotId,
+        publisher: p.publisher,
+        seq: p.snapshotSeq,
+        epoch: p.dataEpoch,
+        controlHead: p.controlHead,
+        frontier: p.frontier,
+        value,
+    });
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/transition.d.ts

@@ -0,0 +1,97 @@
+import { type ControlRecordId, LfcpError, type ResourceId } from "@openlfcp/core";
+import { type CborValue } from "./cbor/index.js";
+import { type ChainProblem, type ControlState } from "./chain.js";
+import { type ControlRecord } from "./control.js";
+/**
+ * Control transitions with compare-and-swap semantics (LFCP-WIRE-01 §21,
+ * §47, §18.1 rule 6). Library logic only: a pure function of the
+ * validated current state, the expected head and the candidate's exact
+ * bytes. No network, clock, randomness or storage; the caller commits an
+ * accepted transition atomically (durable coordinator CAS is server work).
+ *
+ * One head takes one successor: a candidate is accepted only against the
+ * exact current head, so of two candidates built on the same head H, the
+ * first accepted moves the head to H2 and the second then fails its
+ * expected-head check. A caller that refreshes and rebuilds on H2 is
+ * validated again from H2's state, so a one-time invitation already
+ * consumed at H2 refuses the second claim (INVITE_CLAIM_EXHAUSTED).
+ *
+ * Validation reuses validateControlChain from the current state (the
+ * `start` path), with the LFCP-021 capability engine and applyRecord:
+ * there is no second rule set here.
+ */
+export type TransitionResult = {
+    readonly kind: "accepted";
+    readonly nextState: ControlState;
+    readonly record: ControlRecord;
+}
+/**
+ * The candidate is the current head record itself (same record ID, so the
+ * same exact bytes): it is already committed. A server may answer a
+ * repeated put idempotently; how it answers is the server's decision.
+ */
+ | {
+    readonly kind: "already-committed";
+    readonly head: ControlRecordId;
+}
+/** §47: NACK(CONTROL_HEAD_MISMATCH) "with the current head". */
+ | {
+    readonly kind: "head-mismatch";
+    readonly wireCode: "CONTROL_HEAD_MISMATCH";
+    readonly currentHead: ControlRecordId;
+}
+/** §47: Genesis is created with RESOURCE_HOST, never through a Control transition. */
+ | {
+    readonly kind: "genesis";
+    readonly wireCode: "MALFORMED_MESSAGE";
+    readonly reason: string;
+} | {
+    readonly kind: "unauthorized";
+    readonly wireCode: "AUTHORIZATION_FAILED";
+    readonly reason: string;
+}
+/** §18.1 rule 3 after serialization: the invitation is used up. AUTHORIZATION_FAILED on the wire. */
+ | {
+    readonly kind: "claim-exhausted";
+    readonly wireCode: "AUTHORIZATION_FAILED";
+    readonly code: "INVITE_CLAIM_EXHAUSTED";
+    readonly reason: string;
+} | {
+    readonly kind: "invalid";
+    readonly problem: ChainProblem | "NULL_EXPECTED_HEAD";
+    readonly wireCode: string;
+    readonly error: LfcpError;
+};
+/**
+ * Evaluates one candidate Control Record against the validated current
+ * state and the head the submitter expected. Checks, in order: a non-null
+ * expected head; the candidate decodes; it is not already the head; it is
+ * not a Genesis; the expected head is the current head; then the full
+ * successor rules (seq = current + 1, prev = current head, same Resource,
+ * signature by the issuer, authority, claim limit) from the current state.
+ */
+export declare function proposeControlTransition(state: ControlState, expectedHead: Uint8Array | null, candidate: Uint8Array): TransitionResult;
+/** The CONTROL_PUT body (§47). */
+export interface ControlPutBody {
+    readonly resourceId: ResourceId;
+    /** The expected current Control Head (§47: always present). */
+    readonly expectedHead: ControlRecordId;
+    /** The exact signed Control Record bytes. */
+    readonly record: Uint8Array;
+}
+/**
+ * Decodes a control-put-body: {0 resource-id, 1 hash32, 2 bstr} (§47).
+ * "A CONTROL_PUT always names an expected head; a null expected head is
+ * invalid" (§47): null is INVALID_STRUCTURE (MALFORMED_MESSAGE).
+ * Structure only; decodeMessage (message.ts) reads it from a CONTROL_PUT.
+ */
+export declare function controlPutBodyFromCbor(value: CborValue): ControlPutBody;
+/**
+ * A CONTROL_PUT against the coordinator's current state: the body's
+ * Resource must be the state's, and the record must be of that Resource
+ * too; then proposeControlTransition.
+ */
+export declare function proposeControlPut(state: ControlState, body: ControlPutBody): TransitionResult;
+/** Decodes a CONTROL_PUT body from its CBOR bytes (a bare body; decodeMessage decodes whole messages). */
+export declare const decodeControlPutBody: (bytes: Uint8Array) => ControlPutBody;
+//# sourceMappingURL=transition.d.ts.map

package/dist/transition.js

@@ -0,0 +1,130 @@
+import { bytesEqual, controlRecordId, LfcpError, resourceId, toHex, } from "@openlfcp/core";
+import { authorizeControlRecord } from "./capability.js";
+import { decodeStrict } from "./cbor/index.js";
+import { validateControlChain } from "./chain.js";
+import { decodeControlRecord } from "./control.js";
+import { Fields } from "./fields.js";
+/**
+ * Evaluates one candidate Control Record against the validated current
+ * state and the head the submitter expected. Checks, in order: a non-null
+ * expected head; the candidate decodes; it is not already the head; it is
+ * not a Genesis; the expected head is the current head; then the full
+ * successor rules (seq = current + 1, prev = current head, same Resource,
+ * signature by the issuer, authority, claim limit) from the current state.
+ */
+export function proposeControlTransition(state, expectedHead, candidate) {
+    if (expectedHead === null) {
+        // §47: "A CONTROL_PUT always names an expected head; a null expected head is invalid."
+        return Object.freeze({
+            kind: "invalid",
+            problem: "NULL_EXPECTED_HEAD",
+            wireCode: "MALFORMED_MESSAGE",
+            error: new LfcpError("INVALID_STRUCTURE", "an ordinary Control transition needs an expected head"),
+        });
+    }
+    let record;
+    try {
+        record = decodeControlRecord(candidate);
+    }
+    catch (e) {
+        const error = e instanceof LfcpError ? e : new LfcpError("INVALID_STRUCTURE", String(e));
+        return Object.freeze({
+            kind: "invalid",
+            problem: error.code === "UNSUPPORTED_VALUE"
+                ? "UNSUPPORTED_TYPE"
+                : error.code === "INVALID_CONTROL_CHAIN"
+                    ? "SEQUENCE"
+                    : "MALFORMED",
+            wireCode: error.code === "UNSUPPORTED_VALUE" || error.code === "INVALID_CONTROL_CHAIN"
+                ? "INVALID_CONTROL_CHAIN"
+                : "MALFORMED_MESSAGE",
+            error,
+        });
+    }
+    if (bytesEqual(record.signed.id, state.head))
+        return Object.freeze({ kind: "already-committed", head: state.head });
+    if (record.body.type === "GENESIS")
+        return Object.freeze({
+            kind: "genesis",
+            wireCode: "MALFORMED_MESSAGE",
+            reason: "Genesis is created with RESOURCE_HOST, not as a Control transition (§47)",
+        });
+    if (!bytesEqual(expectedHead, state.head))
+        return Object.freeze({
+            kind: "head-mismatch",
+            wireCode: "CONTROL_HEAD_MISMATCH",
+            currentHead: state.head,
+        });
+    let refusal;
+    const result = validateControlChain([candidate], {
+        start: state,
+        authorize: (r, s) => {
+            const decision = authorizeControlRecord(r, s);
+            if (!decision.allowed)
+                refusal = decision;
+            return decision;
+        },
+    });
+    if (result.kind === "linear") {
+        const accepted = result.records[0];
+        if (accepted === undefined)
+            // The only candidate was the head itself, which is handled above.
+            throw new Error("unreachable: an accepted transition without a record");
+        return Object.freeze({ kind: "accepted", nextState: result.state, record: accepted });
+    }
+    if (result.kind === "conflict")
+        // One candidate from one head cannot fork; a second Genesis is refused above.
+        throw new Error("unreachable: a single candidate produced a conflict");
+    if (result.problem === "UNAUTHORIZED" && refusal !== undefined && !refusal.allowed) {
+        if (refusal.code === "INVITE_CLAIM_EXHAUSTED")
+            return Object.freeze({
+                kind: "claim-exhausted",
+                wireCode: "AUTHORIZATION_FAILED",
+                code: "INVITE_CLAIM_EXHAUSTED",
+                reason: refusal.reason,
+            });
+        return Object.freeze({
+            kind: "unauthorized",
+            wireCode: "AUTHORIZATION_FAILED",
+            reason: refusal.reason,
+        });
+    }
+    return Object.freeze({
+        kind: "invalid",
+        problem: result.problem,
+        wireCode: result.wireCode,
+        error: result.error,
+    });
+}
+/**
+ * Decodes a control-put-body: {0 resource-id, 1 hash32, 2 bstr} (§47).
+ * "A CONTROL_PUT always names an expected head; a null expected head is
+ * invalid" (§47): null is INVALID_STRUCTURE (MALFORMED_MESSAGE).
+ * Structure only; decodeMessage (message.ts) reads it from a CONTROL_PUT.
+ */
+export function controlPutBodyFromCbor(value) {
+    const f = new Fields(value, "control-put-body", [0, 1, 2]);
+    return Object.freeze({
+        resourceId: resourceId(f.bytes(0, 32)),
+        expectedHead: controlRecordId(f.bytes(1, 32)),
+        record: f.bytes(2),
+    });
+}
+/**
+ * A CONTROL_PUT against the coordinator's current state: the body's
+ * Resource must be the state's, and the record must be of that Resource
+ * too; then proposeControlTransition.
+ */
+export function proposeControlPut(state, body) {
+    if (!bytesEqual(body.resourceId, state.resourceId))
+        return Object.freeze({
+            kind: "invalid",
+            problem: "RESOURCE",
+            wireCode: "INVALID_CONTROL_CHAIN",
+            error: new LfcpError("INVALID_CONTROL_CHAIN", `the put names Resource ${toHex(body.resourceId)}, not this chain's Resource`),
+        });
+    return proposeControlTransition(state, body.expectedHead, body.record);
+}
+/** Decodes a CONTROL_PUT body from its CBOR bytes (a bare body; decodeMessage decodes whole messages). */
+export const decodeControlPutBody = (bytes) => controlPutBodyFromCbor(decodeStrict(bytes));
+//# sourceMappingURL=transition.js.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@openlfcp/wire",
+  "version": "0.1.0-rc.1",
+  "description": "Deterministic CBOR, COSE and LFCP Wire structures and codecs.",
+  "keywords": [
+    "openlfcp",
+    "lfcp",
+    "local-first",
+    "end-to-end-encryption",
+    "protocol",
+    "cbor",
+    "cose",
+    "wire-format"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/openlfcp/sdk-ts/tree/main/packages/wire#readme",
+  "bugs": {
+    "url": "https://github.com/openlfcp/sdk-ts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openlfcp/sdk-ts.git",
+    "directory": "packages/wire"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cbor": {
+      "types": "./dist/cbor/index.d.ts",
+      "import": "./dist/cbor/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "dependencies": {
+    "@openlfcp/core": "^0.1.0-rc.1",
+    "@openlfcp/crypto": "^0.1.0-rc.1"
+  }
+}