@openlfcp/shared-objects 0.2.2 → 0.3.0

package/dist/identity/replica.d.ts

@@ -0,0 +1,112 @@
+import { type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type CheckedChange, frameSnapshot, unframeChange, unframeSnapshot } from "../admission/framing.js";
+import { type SnapshotLimits } from "../admission/limits.js";
+import { type IdentityValidation } from "./schema.js";
+import { type DeviceEntry, type IdentityWriter, type PairingRequest, type RosterEntry } from "./values.js";
+export interface IdentityOptions {
+    readonly resource: ResourceId;
+    /** Genesis owner; not the current owner of a transferred resource. */
+    readonly root: PrincipalId;
+}
+/** Wire authorization/decryption and class derivation at control_ref happen before this boundary. */
+export interface IdentityUnit extends IdentityWriter {
+    readonly bytes: Uint8Array;
+}
+export interface IdentityRefusal {
+    readonly hash: string | undefined;
+    readonly diagnostic: string;
+    readonly code: string;
+    readonly held: boolean;
+    readonly message: string;
+}
+export interface IdentityReceiveResult {
+    readonly admitted: readonly string[];
+    readonly duplicates: readonly string[];
+    readonly waiting: readonly string[];
+    readonly refused: readonly IdentityRefusal[];
+}
+export type IdentityIntent = {
+    readonly intent: "identity.initialize";
+} | {
+    readonly intent: "roster.put";
+    readonly key: string;
+    readonly entry: RosterEntry;
+} | {
+    readonly intent: "device.put";
+    readonly key: string;
+    readonly entry: DeviceEntry;
+} | {
+    readonly intent: "request.put";
+    readonly key: string;
+    readonly entry: PairingRequest;
+} | {
+    readonly intent: "roster.delete" | "device.delete" | "request.delete";
+    readonly key: string;
+};
+/** Small identity documents: deterministic replay, causal admission, per-entry readers (§§2–4). */
+export declare class IdentityReplica {
+    #private;
+    private constructor();
+    static empty(options: IdentityOptions): IdentityReplica;
+    /** Both plaintext delivery orders are accepted; missing dependencies and held units are retained. */
+    static fromChanges(units: readonly IdentityUnit[], options: IdentityOptions): {
+        readonly replica: IdentityReplica;
+        readonly result: IdentityReceiveResult;
+    };
+    /**
+     * §2.2: no snapshot state is usable without the root's verified unit 1.
+     * Replays the snapshot against verified carrying units for EVERY change:
+     * this also checks historical writer classes and AI4 without trusting a snapshot's author.
+     * Callers fetch/decrypt missing units before retrying (KEY_BLOCKED included).
+     */
+    static fromSave(save: Uint8Array, options: IdentityOptions, verifiedUnits: readonly IdentityUnit[], limits?: SnapshotLimits): IdentityReplica;
+    static fromSnapshot(plaintext: Uint8Array, options: IdentityOptions, verifiedUnits: readonly IdentityUnit[], limits?: SnapshotLimits): IdentityReplica;
+    receive(plaintext: Uint8Array, writer: IdentityWriter): IdentityReceiveResult;
+    receiveChanges(units: readonly IdentityUnit[]): IdentityReceiveResult;
+    /** SOP §14: excluded units and their dependants disappear; held alternatives are retried. */
+    rebuildWithout(exclude: Iterable<string>): {
+        readonly replica: IdentityReplica;
+        readonly result: IdentityReceiveResult;
+    };
+    heads(): string[];
+    hasChange(hash: string): boolean;
+    changes(): Uint8Array[];
+    save(): Uint8Array;
+    snapshot(): Uint8Array;
+    validate(): IdentityValidation;
+    roster(): IdentityValidation["roster"];
+    devices(): IdentityValidation["devices"];
+    requests(): IdentityValidation["requests"];
+    /**
+     * The admitted changes that created or wrote into the value `table[key]`
+     * holds now (every value of a conflict, nested lists and maps included),
+     * in admission (causal) order, each with the signer of the unit that
+     * carried it. Changes to an earlier value since deleted or replaced are
+     * not its provenance. This is the provenance a
+     * managing device checks before it shows a pairing request
+     * (IDENTITY-PROFILE-01 §5.3 step 4: written only by the session's
+     * pairing device) and the change hashes it journals with an approval.
+     */
+    origins(table: "roster" | "devices" | "requests", key: string): readonly {
+        readonly hash: string;
+        readonly signer: PrincipalId;
+    }[];
+    /**
+     * One transaction (one change) for the intent, or for several intents in
+     * order, e.g. the fill change of IDENTITY-PROFILE-01 §5.1 or the devices
+     * entry and the request deletion of §5.3 step 6; scalar strings/uints,
+     * unknown fields preserved on updates.
+     */
+    write(writer: IdentityWriter, intent: IdentityIntent | readonly IdentityIntent[]): CheckedChange;
+}
+export declare const identityCodec: Readonly<{
+    dataProfile: "org.openlfcp.identity.v1";
+    encode: (change: CheckedChange) => Uint8Array;
+    decode: typeof unframeChange;
+}>;
+export declare const identitySnapshotCodec: Readonly<{
+    dataProfile: "org.openlfcp.identity.v1";
+    encode: typeof frameSnapshot;
+    decode: typeof unframeSnapshot;
+}>;
+//# sourceMappingURL=replica.d.ts.map

package/dist/identity/replica.js

@@ -0,0 +1,384 @@
+import * as A from "@automerge/automerge";
+import { bytesEqual, dataEpoch, LfcpError, toHex, } from "@openlfcp/core";
+import { checkChange, checkSaveHeader, frameChange, frameSnapshot, parsedOf, refusedChangeHash, unframeChange, unframeSnapshot, } from "../admission/framing.js";
+import { checkSnapshotExpansion, SNAPSHOT_LIMITS_FLOOR, } from "../admission/limits.js";
+import { ReferenceHistory } from "../admission/references.js";
+import { admitBatch, admitChange } from "../admission/sequence.js";
+import { isWasmTrap } from "../replica.js";
+import { principalRef } from "../values.js";
+import { checkIdentityUnit, IdentityAdmission, refuseIdentity } from "./admission.js";
+import { validateIdentity } from "./schema.js";
+import { deriveIdentityActorId, IDENTITY_PROFILE_ID, } from "./values.js";
+const refusal = (hash, error, held = false) => ({
+    hash,
+    held,
+    code: error instanceof LfcpError ? error.code : "PROFILE_INVALID",
+    diagnostic: error !== null && typeof error === "object" && "diagnostic" in error
+        ? String(error.diagnostic)
+        : held
+            ? "ACTOR_EQUIVOCATION"
+            : "INVALID_AUTOMERGE_BYTES",
+    message: error instanceof Error ? error.message : String(error),
+});
+/** Small identity documents: deterministic replay, causal admission, per-entry readers (§§2–4). */
+export class IdentityReplica {
+    #admission;
+    #options;
+    #accepted = new Map();
+    #waiting = new Map();
+    #sequences = new Map();
+    #references = new ReferenceHistory();
+    get #doc() {
+        return this.#admission.document;
+    }
+    constructor(options) {
+        this.#options = {
+            resource: options.resource.slice(),
+            root: options.root.slice(),
+        };
+        deriveIdentityActorId(options.resource, options.root); // Validate raw ID lengths.
+        const initial = A.init();
+        this.#admission = new IdentityAdmission(initial, this.#options.root);
+        A.free(initial);
+    }
+    #history() {
+        return {
+            hasChange: (hash) => this.#accepted.has(hash),
+            latestSeq: (actor) => this.#sequences.get(actor) ?? 0,
+            references: this.#references,
+        };
+    }
+    #record(change, unit) {
+        this.#accepted.set(change.hash, unit);
+        this.#sequences.set(change.actor, change.seq);
+    }
+    static empty(options) {
+        return new IdentityReplica(options);
+    }
+    /** Both plaintext delivery orders are accepted; missing dependencies and held units are retained. */
+    static fromChanges(units, options) {
+        const replica = IdentityReplica.empty(options);
+        return { replica, result: replica.receiveChanges(units) };
+    }
+    /**
+     * §2.2: no snapshot state is usable without the root's verified unit 1.
+     * Replays the snapshot against verified carrying units for EVERY change:
+     * this also checks historical writer classes and AI4 without trusting a snapshot's author.
+     * Callers fetch/decrypt missing units before retrying (KEY_BLOCKED included).
+     */
+    static fromSave(save, options, verifiedUnits, limits = SNAPSHOT_LIMITS_FLOOR) {
+        checkSaveHeader(save);
+        checkSnapshotExpansion(save, limits);
+        let changes;
+        try {
+            const loaded = A.load(save);
+            try {
+                changes = A.getAllChanges(loaded);
+            }
+            finally {
+                A.free(loaded);
+            }
+        }
+        catch (e) {
+            if (isWasmTrap(e))
+                throw e;
+            refuseIdentity("INVALID_AUTOMERGE_BYTES", `invalid snapshot: ${String(e)}`);
+        }
+        const checked = changes.map(checkChange);
+        const byHash = new Map(verifiedUnits.map((unit) => [checkChange(unit.bytes).hash, unit]));
+        const initial = checked.filter((c) => c.deps.length === 0);
+        if (initial.length !== 1)
+            refuseIdentity("INVALID_ROOT", "snapshot must contain one initial change");
+        const first = initial[0];
+        const proof = byHash.get(first.hash);
+        if (proof === undefined || !bytesEqual(proof.bytes, first.bytes))
+            refuseIdentity("INVALID_ROOT", "fetch and verify the root's unit 1 before using this snapshot");
+        checkIdentityUnit(first, proof, options.resource, options.root);
+        const units = checked.map((change) => {
+            const unit = byHash.get(change.hash);
+            if (unit === undefined || !bytesEqual(unit.bytes, change.bytes))
+                throw new LfcpError("MISSING_DEPENDENCY", `snapshot change ${change.hash} needs its verified carrying unit`);
+            return unit;
+        });
+        const { replica, result } = IdentityReplica.fromChanges(units, options);
+        if (result.refused.length > 0 || result.waiting.length > 0) {
+            const error = result.refused[0];
+            A.free(replica.#doc);
+            throw Object.assign(new LfcpError("PROFILE_INVALID", error?.message ?? "snapshot has missing changes"), {
+                diagnostic: error?.diagnostic ?? "INVALID_AUTOMERGE_BYTES",
+            });
+        }
+        return replica;
+    }
+    static fromSnapshot(plaintext, options, verifiedUnits, limits = SNAPSHOT_LIMITS_FLOOR) {
+        return IdentityReplica.fromSave(unframeSnapshot(plaintext), options, verifiedUnits, limits);
+    }
+    receive(plaintext, writer) {
+        return this.receiveChanges([{ ...writer, bytes: unframeChange(plaintext).bytes }]);
+    }
+    receiveChanges(units) {
+        const refused = [];
+        const pending = new Map(this.#waiting);
+        for (const unit of units) {
+            let change;
+            try {
+                change = checkChange(unit.bytes);
+                checkIdentityUnit(change, unit, this.#options.resource, this.#options.root);
+                if (!pending.has(change.hash))
+                    pending.set(change.hash, {
+                        change,
+                        unit: { ...unit, signer: unit.signer.slice(), bytes: change.bytes },
+                    });
+            }
+            catch (e) {
+                if (isWasmTrap(e))
+                    throw e;
+                refused.push(refusal(change?.hash ?? refusedChangeHash(unit.bytes), e));
+            }
+        }
+        const result = admitBatch([...pending.values()].map((p) => p.change), this.#history(), (c) => this.#admission.accept(c, pending.get(c.hash).unit));
+        for (const refused of result.refused)
+            if (isWasmTrap(refused.error))
+                throw refused.error;
+        this.#waiting.clear();
+        for (const c of result.admitted)
+            this.#record(c, pending.get(c.hash).unit);
+        for (const c of result.waiting)
+            this.#waiting.set(c.hash, pending.get(c.hash));
+        for (const r of result.refused) {
+            refused.push(refusal(r.change.hash, r.error, r.held));
+            if (r.held)
+                this.#waiting.set(r.change.hash, pending.get(r.change.hash));
+        }
+        const hashes = (changes) => Object.freeze(changes.map((c) => c.hash));
+        return Object.freeze({
+            admitted: hashes(result.admitted),
+            duplicates: hashes(result.duplicates),
+            waiting: hashes(result.waiting),
+            refused: Object.freeze(refused),
+        });
+    }
+    /** SOP §14: excluded units and their dependants disappear; held alternatives are retried. */
+    rebuildWithout(exclude) {
+        const removed = new Set(exclude);
+        return IdentityReplica.fromChanges([
+            ...this.#accepted,
+            ...[...this.#waiting].map(([hash, pending]) => [hash, pending.unit]),
+        ]
+            .filter(([hash]) => !removed.has(hash))
+            .map(([, unit]) => unit), this.#options);
+    }
+    heads() {
+        return A.getHeads(this.#doc).sort();
+    }
+    hasChange(hash) {
+        return this.#accepted.has(hash);
+    }
+    changes() {
+        return A.getAllChanges(this.#doc);
+    }
+    save() {
+        return A.save(this.#doc);
+    }
+    snapshot() {
+        return frameSnapshot(this.save());
+    }
+    validate() {
+        return validateIdentity(this.#doc, this.#options.root);
+    }
+    roster() {
+        return this.validate().roster;
+    }
+    devices() {
+        return this.validate().devices;
+    }
+    requests() {
+        return this.validate().requests;
+    }
+    /**
+     * The admitted changes that created or wrote into the value `table[key]`
+     * holds now (every value of a conflict, nested lists and maps included),
+     * in admission (causal) order, each with the signer of the unit that
+     * carried it. Changes to an earlier value since deleted or replaced are
+     * not its provenance. This is the provenance a
+     * managing device checks before it shows a pairing request
+     * (IDENTITY-PROFILE-01 §5.3 step 4: written only by the session's
+     * pairing device) and the change hashes it journals with an approval.
+     */
+    origins(table, key) {
+        // The values `table[key]` holds now: one, or several under a conflict. Each
+        // is named by the op that set it (for a map, its object ID). The history of
+        // earlier values deleted or overwritten since is not their provenance.
+        const container = this.#doc[table];
+        const current = new Set();
+        if (container !== null && typeof container === "object" && Object.hasOwn(container, key)) {
+            const conflicts = A.getConflicts(container, key);
+            if (conflicts !== undefined)
+                for (const id of Object.keys(conflicts))
+                    current.add(id);
+            else {
+                const value = container[key];
+                const id = value !== null && typeof value === "object" ? A.getObjectId(value) : null;
+                if (id !== null && id !== undefined)
+                    current.add(id);
+            }
+        }
+        const entry = new Set(current);
+        const out = [];
+        if (current.size === 0)
+            return Object.freeze(out);
+        for (const [hash, unit] of this.#accepted) {
+            const change = A.decodeChange(unit.bytes);
+            let touched = false;
+            change.ops.forEach((op, i) => {
+                const id = `${change.startOp + i}@${change.actor}`;
+                const makes = op.action === "makeMap" || op.action === "makeList";
+                if (current.has(id) || entry.has(op.obj)) {
+                    touched = true;
+                    if (makes)
+                        entry.add(id);
+                }
+            });
+            if (touched)
+                out.push({ hash, signer: unit.signer.slice() });
+        }
+        return Object.freeze(out);
+    }
+    /**
+     * One transaction (one change) for the intent, or for several intents in
+     * order, e.g. the fill change of IDENTITY-PROFILE-01 §5.1 or the devices
+     * entry and the request deletion of §5.3 step 6; scalar strings/uints,
+     * unknown fields preserved on updates.
+     */
+    write(writer, intent) {
+        const intents = Array.isArray(intent)
+            ? intent
+            : [intent];
+        if (intents.length === 0)
+            throw new LfcpError("PROFILE_INVALID", "no intent to write");
+        // AI5 (§3) refuses the change anyway; say why before building it.
+        for (const i of intents)
+            if (i.intent === "device.put" &&
+                i.entry.missing_keys !== undefined &&
+                i.key !== principalRef(writer.signer))
+                refuseIdentity("UNAUTHORIZED_WRITER", "a device writes only its own missing_keys hints (§3 AI5)");
+        const actor = toHex(deriveIdentityActorId(this.#options.resource, writer.signer));
+        const fork = A.clone(this.#doc, { actor });
+        let bytes;
+        try {
+            const doc = A.change(fork, { time: 0 }, (d) => {
+                for (const i of intents)
+                    applyIntent(d, i, this.#options.root, A.getBackend(d));
+            });
+            const last = A.getLastLocalChange(doc);
+            if (last === null || last === undefined)
+                throw new LfcpError("PROFILE_INVALID", "the intent did not create a change");
+            bytes = last;
+            const validation = validateIdentity(doc, this.#options.root);
+            for (const i of intents) {
+                const base = "key" in i ? `/${tableOf(i)}/${i.key}` : "";
+                const problem = validation.problems.find((p) => p.diagnostic === "INVALID_ROOT" ||
+                    p.pointer === base ||
+                    p.pointer.startsWith(`${base}/`));
+                if (problem !== undefined)
+                    throw Object.assign(new LfcpError("PROFILE_INVALID", problem.message), {
+                        diagnostic: problem.diagnostic,
+                    });
+            }
+        }
+        finally {
+            A.free(fork);
+        }
+        const change = checkChange(bytes);
+        // Check only this candidate against the current indexes. Failed local
+        // writes never enter the waiting queue or consume an actor sequence.
+        checkIdentityUnit(change, writer, this.#options.resource, this.#options.root);
+        const decision = admitChange(change, this.#history());
+        if (decision.kind === "invalid" || decision.kind === "held")
+            throw decision.error;
+        if (decision.kind === "missing")
+            throw new LfcpError("MISSING_DEPENDENCY", "local change is not admissible");
+        if (decision.kind === "next") {
+            this.#admission.accept(change, writer);
+            this.#references.add(change.hash, parsedOf(change));
+            this.#record(change, {
+                ...writer,
+                signer: writer.signer.slice(),
+                bytes: change.bytes,
+            });
+            if (this.#waiting.size > 0)
+                this.receiveChanges([]);
+        }
+        // Keep the byte log private even if callers mutate the returned buffer.
+        return checkChange(bytes);
+    }
+}
+const tableOf = (intent) => intent.intent.startsWith("roster.")
+    ? "roster"
+    : intent.intent.startsWith("device.")
+        ? "devices"
+        : "requests";
+function applyIntent(d, intent, root, backend) {
+    if (intent.intent === "identity.initialize") {
+        if (Object.keys(d).length !== 0)
+            refuseIdentity("INVALID_ROOT", "identity is already initialized");
+        d.profile = new A.ImmutableString(IDENTITY_PROFILE_ID);
+        d.identity = { root: new A.ImmutableString(principalRef(root)) };
+        for (const key of ["roster", "devices", "requests", "extensions"])
+            d[key] = {};
+        return;
+    }
+    const map = d[tableOf(intent)];
+    if (map === undefined)
+        refuseIdentity("INVALID_ROOT", "initialize the identity first");
+    if (!("entry" in intent)) {
+        delete map[intent.key];
+        return;
+    }
+    if (!Object.hasOwn(map, intent.key))
+        map[intent.key] = {};
+    const entry = map[intent.key];
+    for (const [key, value] of Object.entries(intent.entry))
+        if (value !== undefined)
+            putValue(entry, key, value, backend);
+}
+function putValue(target, key, value, backend) {
+    const map = target;
+    if (typeof value === "string")
+        map[key] = new A.ImmutableString(value);
+    else if (typeof value === "number")
+        map[key] = new A.Uint(value);
+    else if (typeof value === "bigint") {
+        // Uint's JS wrapper is limited to safe numbers; the backend accepts the full uint64.
+        const id = A.getObjectId(target);
+        const epoch = dataEpoch(value);
+        if (Array.isArray(target) && Number(key) === backend.length(id))
+            backend.insert(id, Number(key), epoch, "uint");
+        else
+            backend.put(id, key, epoch, "uint");
+    }
+    else if (Array.isArray(value)) {
+        map[key] = [];
+        value.forEach((v, i) => {
+            putValue(map[key], i, v, backend);
+        });
+    }
+    else if (value !== null && typeof value === "object") {
+        map[key] = {};
+        for (const [k, v] of Object.entries(value))
+            putValue(map[key], k, v, backend);
+    }
+    else
+        map[key] = value;
+}
+export const identityCodec = Object.freeze({
+    dataProfile: IDENTITY_PROFILE_ID,
+    encode: (change) => frameChange(change.bytes),
+    decode: unframeChange,
+});
+export const identitySnapshotCodec = Object.freeze({
+    dataProfile: IDENTITY_PROFILE_ID,
+    encode: frameSnapshot,
+    decode: unframeSnapshot,
+});
+//# sourceMappingURL=replica.js.map

package/dist/identity/schema.d.ts

@@ -0,0 +1,22 @@
+import type * as A from "@automerge/automerge";
+import { type PrincipalId } from "@openlfcp/core";
+import { type DeviceEntry, type PairingRequest, type RosterEntry } from "./values.js";
+export declare const IDENTITY_DIAGNOSTIC_ORDER: readonly ["INVALID_ROOT", "MISSING_REQUIRED_FIELD", "INVALID_FIELD_TYPE", "INVALID_RESOURCE_REF", "INVALID_PRINCIPAL_REF", "INVALID_DESCRIPTOR", "INVALID_ENUM_VALUE", "INVALID_TIMESTAMP", "INVALID_EXTENSION_NAMESPACE"];
+export type IdentityDiagnostic = (typeof IDENTITY_DIAGNOSTIC_ORDER)[number];
+export interface IdentityProblem {
+    readonly code: "PROFILE_INVALID";
+    readonly diagnostic: IdentityDiagnostic;
+    readonly pointer: string;
+    readonly message: string;
+}
+export interface IdentityValidation {
+    /** False only for an invalid root; invalid entries do not poison other entries. */
+    readonly usable: boolean;
+    readonly problems: readonly IdentityProblem[];
+    readonly roster: Readonly<Record<string, RosterEntry>>;
+    readonly devices: Readonly<Record<string, DeviceEntry>>;
+    readonly requests: Readonly<Record<string, PairingRequest>>;
+}
+/** §4: validate every concurrent value; return only usable entries, never request winners. */
+export declare function validateIdentity(doc: A.Doc<unknown>, root: PrincipalId): IdentityValidation;
+//# sourceMappingURL=schema.d.ts.map