@openlfcp/client 0.2.2 → 0.3.1

package/dist/identity/context.js

@@ -0,0 +1,495 @@
+import { actorSequence, bytesEqual, controlRecordId, dataEpoch, fromHex, hash32, LfcpError, toHex, } from "@openlfcp/core";
+import { dekCommitment, exportSecretKeyBytes, importResourceDEK, sha256, } from "@openlfcp/crypto";
+import { dekSecretRef } from "@openlfcp/storage";
+import { ABILITY, hasAbility, InMemorySeenUnits, parseDataUnit, parseKeyPackage, receiveDataUnit, receiveKeyPackage, sealDataUnit, sealKeyPackage, validateControlChain, verifyKeyPackage, verifySignedObject, } from "@openlfcp/wire";
+import { adoptStoredDeks, checkWriteBarrier, loadControlChain, saveControlChain, saveControlConflict, } from "../storage.js";
+import { identityPlaintextCodec, identityWriterClass, } from "./document.js";
+import { phaseOf, } from "./journal.js";
+import { IdentityUnavailable } from "./network.js";
+/** The Resource or the Identity Resource is forked (§9.7): approval, reconciliation and rotation are suspended. */
+export class IdentityConflict extends Error {
+    resource;
+    constructor(resource, message) {
+        super(message);
+        this.resource = resource;
+        this.name = "IdentityConflict";
+    }
+}
+/**
+ * Synchronises the Control Chain of `resource` from the coordinator and
+ * stores it: the local chain extended with the coordinator's later
+ * records, or the coordinator's whole chain when the local one does not
+ * extend. A fork is stored as a conflict and thrown (§9.7).
+ */
+export async function syncChain(storage, channel, resource) {
+    // A fork this installation already knows stays blocking (§9.7): no branch is chosen.
+    if ((await storage.control.conflict(resource)) !== undefined)
+        throw new IdentityConflict(resource, "the Control Chain is forked (§9.7)");
+    const local = await loadControlChain(storage, resource);
+    const have = local?.kind === "linear" ? local.records.map((r) => r.signed.bytes) : [];
+    let chain = validateControlChain([
+        ...have,
+        ...(await channel.control(resource, BigInt(have.length))),
+    ]);
+    if (chain.kind !== "linear" && have.length > 0) {
+        // The coordinator's chain does not extend the stored one: validate both
+        // together, so a competing record on a known prev is a conflict (§9.7),
+        // never a silent switch to the coordinator's branch.
+        const all = new Map();
+        for (const r of [...have, ...(await channel.control(resource, 0n))])
+            all.set(toHex(sha256(r)), r);
+        chain = validateControlChain([...all.values()]);
+    }
+    if (chain.kind === "conflict") {
+        await saveControlConflict(storage, resource, chain);
+        throw new IdentityConflict(resource, "the Control Chain is forked (§9.7)");
+    }
+    if (chain.kind !== "linear")
+        throw new LfcpError("INVALID_CONTROL_CHAIN", "the coordinator's Control Chain does not validate");
+    if (!bytesEqual(chain.state.resourceId, resource))
+        throw new LfcpError("INVALID_CONTROL_CHAIN", "the coordinator sent another Resource's chain");
+    await storeChain(storage, chain, local?.kind === "linear" ? local : undefined);
+    return chain;
+}
+async function storeChain(storage, chain, previous) {
+    if (previous !== undefined && bytesEqual(previous.state.head, chain.state.head))
+        return;
+    const prefix = previous !== undefined &&
+        previous.records.length <= chain.records.length &&
+        previous.records.every((r, i) => bytesEqual(r.signed.id, chain.records[i]?.signed.id ?? new Uint8Array()));
+    const r = await saveControlChain(storage, chain, prefix ? previous.state.head : null);
+    if (!r.ok && prefix)
+        throw new Error(`the Control Chain was not stored: ${r.reason}`);
+}
+/** Validates `chain` extended with `record` (e.g. after an ACK) and stores it. */
+export async function extendChain(storage, chain, record) {
+    const next = validateControlChain([...chain.records.map((r) => r.signed.bytes), record]);
+    if (next.kind !== "linear")
+        throw new LfcpError("INVALID_CONTROL_CHAIN", "an acknowledged record does not validate locally");
+    await storeChain(storage, next, chain);
+    return next;
+}
+const MAX_HEAD_RETRIES = 8;
+/**
+ * Runs one Control Plane phase durably (§9.1–§9.3). The phase is
+ * classified on the synchronised chain first; while it is `pending`, the
+ * exact bytes are persisted before they are sent: the same bytes again
+ * while the head is the one they were built on (a lost ACK is answered
+ * with the same ACK, W §47), a record rebuilt on a new head otherwise.
+ */
+export async function runControlPhase(storage, channel, journal, operation, spec) {
+    const R = spec.resource;
+    for (let attempt = 0;; attempt++) {
+        const chain = await syncChain(storage, channel, R);
+        const before = phaseOf(await journal.load(operation), spec.id);
+        const sent = new Set(before?.sent ?? []);
+        const state = spec.classify(chain, (id) => sent.has(id));
+        if (state !== "pending") {
+            const recordId = state === "committed-own" ? ownRecordOn(chain, sent) : undefined;
+            await journal.putPhase(operation, {
+                ...(before ?? {}),
+                id: spec.id,
+                kind: spec.kind,
+                resource: toHex(R),
+                state,
+                ...(spec.facts === undefined ? {} : { facts: spec.facts }),
+                ...(recordId === undefined ? {} : { recordId }),
+            });
+            return Object.freeze({
+                state,
+                chain,
+                ...(recordId === undefined ? {} : { recordId: controlRecordId(fromHex(recordId)) }),
+            });
+        }
+        if (attempt >= MAX_HEAD_RETRIES)
+            throw new IdentityUnavailable(`the head kept moving while proposing ${spec.id}`);
+        const head = toHex(chain.state.head);
+        let bytes;
+        if (spec.resend !== false && before?.bytes !== undefined && before.expectedHead === head)
+            bytes = fromHex(before.bytes);
+        else {
+            bytes = await spec.build(chain);
+            const id = toHex(validateRecordId(bytes));
+            await journal.putPhase(operation, {
+                id: spec.id,
+                kind: spec.kind,
+                resource: toHex(R),
+                state: "pending",
+                bytes: toHex(bytes),
+                expectedHead: head,
+                sent: [...sent, id],
+                ...(spec.facts === undefined ? {} : { facts: spec.facts }),
+            });
+        }
+        const answer = await channel.putControl(R, chain.state.head, bytes);
+        if (answer.kind === "ack") {
+            const next = await extendChain(storage, chain, bytes);
+            const recordId = toHex(next.state.head);
+            const phase = phaseOf(await journal.load(operation), spec.id);
+            await journal.putPhase(operation, { ...phase, state: "committed-own", recordId });
+            return Object.freeze({ state: "committed-own", chain: next, recordId: next.state.head });
+        }
+        if (answer.code === "CONTROL_HEAD_MISMATCH")
+            continue;
+        const phase = phaseOf(await journal.load(operation), spec.id);
+        await journal.putPhase(operation, { ...phase, state: "refused", code: answer.code });
+        return Object.freeze({ state: "refused", chain, code: answer.code });
+    }
+}
+/** A Control Record's ID: SHA-256 of its exact bytes (W §13). */
+const validateRecordId = (bytes) => controlRecordId(sha256(bytes));
+function ownRecordOn(chain, sent) {
+    for (const r of chain.records) {
+        const id = toHex(r.signed.id);
+        if (sent.has(id))
+            return id;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// DEKs
+/** The DEKs this client holds for `chain`'s epochs, each checked against its commitment. */
+export async function heldDeks(secrets, chain) {
+    const R = chain.state.resourceId;
+    const out = new Map();
+    for (const e of chain.state.epochs.values()) {
+        const bytes = await secrets.get(dekSecretRef(R, e.epoch));
+        if (bytes === undefined)
+            continue;
+        try {
+            const dek = importResourceDEK(bytes);
+            if (bytesEqual(dekCommitment(R, e.epoch, dek), e.dekCommitment))
+                out.set(String(e.epoch), dek);
+        }
+        finally {
+            bytes.fill(0);
+        }
+    }
+    return out;
+}
+/** Stores the DEK of `epoch` (secret first) and links the epoch rows to it (LFCP-034). */
+export async function storeDek(storage, secrets, chain, epoch, dek) {
+    const e = chain.state.epochs.get(String(epoch));
+    if (e !== undefined &&
+        !bytesEqual(dekCommitment(chain.state.resourceId, epoch, dek), e.dekCommitment))
+        throw new LfcpError("DEK_COMMITMENT_MISMATCH", `the DEK is not the one committed for epoch ${epoch}`);
+    const bytes = exportSecretKeyBytes(dek);
+    try {
+        await secrets.put(dekSecretRef(chain.state.resourceId, epoch), bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+    await adoptStoredDeks(storage, secrets, chain);
+}
+/**
+ * KEY_PACKAGE_GET for `recipient` over every epoch of `chain` (§52: at most
+ * 256 per request, the channel splits), opening and storing each DEK.
+ */
+export async function fetchDeks(storage, secrets, channel, chain, recipient) {
+    const R = chain.state.resourceId;
+    const out = await heldDeks(secrets, chain);
+    const missing = [...chain.state.epochs.values()]
+        .map((e) => e.epoch)
+        .filter((e) => !out.has(String(e)));
+    if (missing.length === 0)
+        return out;
+    for (const bytes of await channel.keyPackages(R, recipient.signer.descriptor.principalId, missing)) {
+        const r = await receiveKeyPackage(chain, bytes, {
+            descriptor: recipient.signer.descriptor,
+            agreement: recipient.agreement,
+        });
+        if (r.kind !== "opened" || out.has(String(r.epoch)))
+            continue;
+        await storeDek(storage, secrets, chain, r.epoch, r.dek);
+        out.set(String(r.epoch), r.dek);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Readers and key delivery
+/** Every Principal with `holds(P, 1)` at the head (W §19, §25.2): the reader set, by ID. */
+export function readersAt(state) {
+    const all = new Map([
+        [toHex(state.owner.principalId), state.owner],
+        ...[...state.principals.entries()],
+    ]);
+    return Object.freeze([...all.entries()]
+        .filter(([, d]) => hasAbility(state, d.principalId, ABILITY.DATA_READ))
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([, d]) => d));
+}
+/**
+ * Seals every DEK of `deks` to each recipient at the chain's head and
+ * records each acknowledged package (§9.5). A package the ledger records is
+ * `complete` unless `resend` lists its epoch for that recipient (a
+ * `missing_keys` hint, §7.1 step 3); a recipient that is no longer a
+ * reader, or a package that would not be authorized, is skipped (§9.2).
+ */
+export async function deliverKeys(options) {
+    const { chain, sender, ledger } = options;
+    const R = chain.state.resourceId;
+    const sent = [];
+    const skipped = [];
+    let complete = 0;
+    const epochs = [...options.deks.keys()].sort((a, b) => (BigInt(a) < BigInt(b) ? -1 : 1));
+    for (const recipient of options.recipients) {
+        const rid = recipient.principalId;
+        const hex = toHex(rid);
+        if (bytesEqual(rid, sender.descriptor.principalId))
+            continue;
+        if (!hasAbility(chain.state, rid, ABILITY.DATA_READ)) {
+            skipped.push({ recipient: hex, reason: "not a reader at the head" });
+            continue;
+        }
+        for (const e of epochs) {
+            const epoch = dataEpoch(BigInt(e));
+            if ((await ledger.has(R, epoch, rid)) && !(options.resend?.get(hex)?.has(e) ?? false)) {
+                complete++;
+                continue;
+            }
+            // §9.1: a package sent before is sent again as the same bytes, while it is still authorized.
+            let bytes = await ledger.pending(R, epoch, rid);
+            if (bytes !== undefined &&
+                verifyKeyPackage(chain, parseKeyPackage(bytes)).kind !== "authorized")
+                bytes = undefined;
+            if (bytes === undefined) {
+                const sealed = await sealKeyPackage({
+                    resourceId: R,
+                    epoch,
+                    controlHead: chain.state.head,
+                    recipient,
+                    dek: options.deks.get(e),
+                    signer: sender,
+                });
+                const check = verifyKeyPackage(chain, parseKeyPackage(sealed.bytes));
+                if (check.kind !== "authorized") {
+                    skipped.push({ recipient: hex, reason: check.message });
+                    break;
+                }
+                bytes = sealed.bytes;
+                await ledger.putPending(R, epoch, rid, bytes);
+            }
+            const answer = await options.channel.putKeyPackage(R, bytes);
+            if (answer.kind !== "ack") {
+                skipped.push({ recipient: hex, reason: answer.code });
+                continue;
+            }
+            await ledger.record({
+                resource: R,
+                epoch,
+                recipient: rid,
+                packageId: hash32(parseKeyPackage(bytes).signed.id),
+            });
+            sent.push({ epoch, recipient: hex });
+        }
+    }
+    return Object.freeze({ sent: Object.freeze(sent), complete, skipped: Object.freeze(skipped) });
+}
+// ---------------------------------------------------------------------------
+// The Identity Resource's document
+/**
+ * Fetches every Data Unit of the Identity Resource that the coordinator
+ * advertises and applies the readable ones to `doc` in actor-sequence
+ * order, each with its writer class at its control_ref (§2.3). Returns the
+ * highest accepted sequence per actor (hex).
+ */
+export async function loadIdentityDocument(options) {
+    const { chain, doc } = options;
+    const R = chain.state.resourceId;
+    const root = genesisOwner(chain);
+    const opened = await options.channel.open(R);
+    if (opened.kind === "nack")
+        throw new IdentityUnavailable(`RESOURCE_OPEN was refused: ${opened.code}`);
+    const ranges = opened.haves.flatMap((h) => {
+        const out = h.contiguous > 0n ? [{ actor: h.principalId, start: 1n, end: h.contiguous }] : [];
+        for (const [start, end] of h.ranges ?? [])
+            out.push({ actor: h.principalId, start, end });
+        return out;
+    });
+    // Units in the order of their Control Heads, then by actor and sequence: a writer
+    // synchronises before writing, so a change rarely references a head older than
+    // the changes it saw, and changes reach the document after their dependencies
+    // (a held change is still admitted later; provenance comes from the port).
+    // Both units of an equivocation are excluded first (W §26.2).
+    const headSeq = (head) => chain.stateAt(head)?.seq ?? chain.state.seq + 1n;
+    const units = withoutEquivocations(chain, (await options.channel.dataUnits(R, ranges)).map((bytes) => {
+        const parsed = parseDataUnit(bytes);
+        return { bytes, parsed, at: headSeq(parsed.payload.controlHead) };
+    })).sort((a, b) => {
+        if (a.at !== b.at)
+            return a.at < b.at ? -1 : 1;
+        const x = toHex(a.parsed.payload.actor);
+        const y = toHex(b.parsed.payload.actor);
+        if (x !== y)
+            return x < y ? -1 : 1;
+        return a.parsed.payload.actorSeq < b.parsed.payload.actorSeq ? -1 : 1;
+    });
+    const seen = new InMemorySeenUnits();
+    const latest = new Map();
+    const pending = [];
+    const apply = (plaintext, author) => doc.receive(plaintext, author);
+    for (const { bytes, parsed } of units) {
+        const r = await receiveDataUnit(chain, bytes, {
+            seen,
+            dek: (epoch) => options.deks.get(String(epoch)),
+            profile: identityPlaintextCodec,
+        });
+        if (r.kind !== "accepted")
+            continue;
+        const at = chain.stateAt(parsed.payload.controlHead) ?? chain.state;
+        const author = {
+            signer: r.actor,
+            actorSeq: r.seq,
+            writerClass: identityWriterClass(at, root, r.actor),
+        };
+        if (!apply(r.value, author))
+            pending.push({ plaintext: r.value, author, unitId: r.unitId });
+        latest.set(toHex(r.actor), { seq: r.seq, unitId: r.unitId });
+    }
+    // Changes of other actors that depend on a change applied later (SOP §14.1).
+    for (let progress = true; progress && pending.length > 0;) {
+        progress = false;
+        for (let i = 0; i < pending.length;) {
+            const p = pending[i];
+            if (apply(p.plaintext, p.author)) {
+                pending.splice(i, 1);
+                progress = true;
+            }
+            else
+                i++;
+        }
+    }
+    const unapplied = pending.map((p) => Object.freeze({ actor: p.author.signer, seq: p.author.actorSeq, unitId: p.unitId }));
+    return { latest, unapplied: Object.freeze(unapplied) };
+}
+/** The Genesis owner of a chain: the root of an Identity Resource (§2.3). */
+export function genesisOwner(chain) {
+    const g = chain.records[0];
+    return g?.body.type === "GENESIS" ? g.body.owner.principalId : chain.state.owner.principalId;
+}
+/**
+ * A new unit of `signer` in the Identity Resource carrying `intents` as
+ * one change: the next actor sequence from the storage's reservation
+ * (durable, never reused), the current epoch's DEK, the signer's latest
+ * accepted unit as previous. The change is applied to `doc`.
+ */
+export async function sealIdentityUnit(options) {
+    const { chain, signer } = options;
+    const R = chain.state.resourceId;
+    await checkWriteBarrier(options.storage, R);
+    const epoch = chain.state.epoch.epoch;
+    const dek = options.deks.get(String(epoch));
+    if (dek === undefined)
+        throw new LfcpError("KEY_PACKAGE_OPEN_FAILED", `the DEK of epoch ${epoch} is not held`);
+    const me = signer.descriptor.principalId;
+    const previous = options.latest.get(toHex(me));
+    let seq = options.seq;
+    if (seq === undefined) {
+        seq = await options.storage.actorSequences.reserveNext(R, me);
+        while (previous !== undefined && seq <= previous.seq)
+            seq = await options.storage.actorSequences.reserveNext(R, me);
+    }
+    const plaintext = options.doc.write({
+        signer: me,
+        actorSeq: seq,
+        writerClass: identityWriterClass(chain.state, genesisOwner(chain), me),
+    }, options.intents);
+    return sealDataUnit({
+        resourceId: R,
+        dataEpoch: epoch,
+        actorSeq: actorSequence(seq),
+        prevDataUnitId: previous?.unitId ?? null,
+        controlHead: chain.state.head,
+    }, plaintext, dek, signer).bytes;
+}
+/**
+ * W §26.2: two different units at one (resource, actor, sequence), each
+ * with a valid signature by its actor, are equivocation, and both are
+ * excluded (their dependants then wait for a dependency that never comes:
+ * the actor's later units for its hash chain, other changes for the
+ * document's). Only units of `chain`'s Resource whose signature verifies
+ * take part: an unsigned or forged copy proves nothing and is dropped
+ * without excluding the signed unit. Authorization and decryption are not
+ * conditions here. Deciding before anything is applied keeps the result
+ * independent of the delivery order.
+ */
+export function withoutEquivocations(chain, units) {
+    const signed = units.filter((u) => {
+        const p = u.parsed.payload;
+        if (!bytesEqual(p.resourceId, chain.state.resourceId))
+            return false;
+        const actor = chain.state.principals.get(toHex(p.actor));
+        return actor !== undefined && verifySignedObject(u.parsed.signed, actor).valid;
+    });
+    const key = (u) => `${toHex(u.parsed.payload.actor)}:${u.parsed.payload.actorSeq}`;
+    const ids = new Map();
+    for (const u of signed) {
+        const set = ids.get(key(u)) ?? new Set();
+        set.add(toHex(sha256(u.bytes)));
+        ids.set(key(u), set);
+    }
+    return signed.filter((u) => (ids.get(key(u))?.size ?? 0) <= 1);
+}
+/**
+ * Sends one Data Unit durably (§9.1): its exact bytes are persisted before
+ * they are sent and re-sent as they are after a restart, so an actor
+ * sequence is never used twice (W §26.2). A coordinator answers a unit it
+ * already holds with the same ACK.
+ */
+export async function runUnitPhase(channel, journal, operation, spec) {
+    for (let attempt = 0;; attempt++) {
+        const before = phaseOf(await journal.load(operation), spec.id);
+        if (before?.state === "committed-own")
+            return { state: "committed-own" };
+        if (before?.state === "complete")
+            return { state: "complete" };
+        const retry = before?.state === "refused" &&
+            before.code !== undefined &&
+            ((spec.rebuildOn ?? []).includes(before.code) ||
+                (attempt === 0 && spec.rebuildRefused === true));
+        if (retry && attempt > 3)
+            return { state: "refused", code: before?.code ?? "refused" };
+        let bytes;
+        if (before?.bytes !== undefined && !retry)
+            bytes = fromHex(before.bytes);
+        else {
+            const built = await spec.build();
+            const facts = before?.bytes !== undefined && retry
+                ? { facts: { ...before.facts, [`stale${attempt}`]: before.bytes } }
+                : before?.facts === undefined
+                    ? {}
+                    : { facts: before.facts };
+            if (built === null) {
+                // Another hand wrote the effect on the state the unit would build on (§9.2).
+                await journal.putPhase(operation, {
+                    id: spec.id,
+                    kind: "unit",
+                    resource: toHex(spec.resource),
+                    state: "complete",
+                    ...facts,
+                });
+                return { state: "complete" };
+            }
+            bytes = built;
+            await journal.putPhase(operation, {
+                id: spec.id,
+                kind: "unit",
+                resource: toHex(spec.resource),
+                state: "pending",
+                bytes: toHex(bytes),
+                ...facts,
+            });
+        }
+        const answer = await channel.putDataUnit(spec.resource, bytes);
+        const phase = phaseOf(await journal.load(operation), spec.id);
+        if (answer.kind === "ack") {
+            await journal.putPhase(operation, { ...phase, state: "committed-own" });
+            return { state: "committed-own" };
+        }
+        await journal.putPhase(operation, { ...phase, state: "refused", code: answer.code });
+        if (!(spec.rebuildOn ?? []).includes(answer.code))
+            return { state: "refused", code: answer.code };
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/identity/devices.d.ts

@@ -0,0 +1,127 @@
+import { type PrincipalId, type ResourceId } from "@openlfcp/core";
+import type { SecretStore } from "@openlfcp/storage";
+import { type CertificateChain, type ControlState, type DataProfileCodec, type DeviceCertificate, type DeviceCertificatePayload, type DeviceKind, type PrincipalDescriptor, type Signer } from "@openlfcp/wire";
+import { type IdentityStorage, type Installation, type KeyDelivery } from "./context.js";
+import { type IdentityNetwork } from "./network.js";
+import { type LinearChain } from "./phases.js";
+/** The mask presets of IDENTITY-PROFILE-01 §5.4 (decision I6). Codes 9 and 11 are never listed. */
+export declare const MASK_PRESETS: Readonly<{
+    readonly full: Readonly<{
+        kind: 0;
+        mask: bigint[];
+    }>;
+    readonly edit: Readonly<{
+        kind: 0;
+        mask: bigint[];
+    }>;
+    readonly read: Readonly<{
+        kind: 0;
+        mask: bigint[];
+    }>;
+    readonly service: Readonly<{
+        kind: 1;
+        mask: bigint[];
+    }>;
+}>;
+export type MaskPreset = keyof typeof MASK_PRESETS;
+/** What every identity flow needs of the installation. */
+export interface FlowOptions {
+    readonly installation: Installation;
+    readonly storage: IdentityStorage;
+    readonly secrets: SecretStore;
+    readonly network: IdentityNetwork;
+    readonly now: () => number;
+    /**
+     * The application's Data Profile codecs. A rotation uses the Resource's
+     * codec to judge which units recipients accept as data (W §26.3 rule 7);
+     * without one, only decryption and recorded refusals are checked.
+     */
+    readonly dataProfiles?: readonly DataProfileCodec<unknown>[];
+}
+/**
+ * The certificates above a leaf that `issuer` signs for `root` in the
+ * state: none when the issuer is the root, else the issuer's own current
+ * chain, which must be active there (W §7.3 (c3), §17.4 rule 6).
+ */
+export declare function issuerCertificates(state: ControlState, issuer: PrincipalId, root: PrincipalId): readonly DeviceCertificate[] | undefined;
+/** A leaf payload for `device` with a fresh serial (W §7.3). */
+export declare function leafPayload(root: PrincipalId, device: PrincipalDescriptor, kind: DeviceKind, mask: readonly bigint[], scope: readonly ResourceId[]): DeviceCertificatePayload;
+export type Feasibility = {
+    readonly feasible: true;
+} | {
+    readonly feasible: false;
+    readonly reason: string;
+};
+/**
+ * IDENTITY-PROFILE-01 §5.3 step 4: whether the DEVICE_GRANT that would
+ * register (or bind) `leaf` through `issuer` would be accepted by the
+ * Resource's current state, before anything is committed or signed for
+ * the device (N9). The complete future chain is built with the leaf's
+ * signature taken as given (a placeholder never leaves this function) and
+ * checked with the validators' own rules: structure (kind, mask, scope,
+ * c1, c5, c7), c3 and c4 against the issuer's chain, and W §17.4 rules 4
+ * to 8 on the state after `consume` when a pairing session is given (its
+ * device then counts as revoked, rule 8), else on the current state.
+ */
+export declare function checkIssuance(options: {
+    readonly chain: LinearChain;
+    readonly issuer: Signer;
+    readonly leaf: DeviceCertificatePayload;
+    /** The pairing device whose consume precedes the grant (§5.3 step 5). */
+    readonly pairing?: PrincipalId;
+}): Feasibility;
+/** Signs `leaf` through `issuer` and returns the complete chain (§5.3 step 6). */
+export declare function signChain(state: ControlState, issuer: Signer, leaf: DeviceCertificatePayload): CertificateChain;
+/**
+ * Whether `actor` may propose device records for `root`'s devices in the
+ * Resource (§5.3 step 10, §7.1): it is the root, an active device of the
+ * root with `12`, or, when the root owns the Resource, an active device
+ * with `13`.
+ */
+export declare function mayManageDevices(state: ControlState, actor: PrincipalId, root: PrincipalId): boolean;
+/** Where a device registration ended in one Resource. */
+export type RegistrationStatus = 
+/** The record is committed (or the effect already existed); keys follow. */
+"registered"
+/** The leaf or an issuer is revoked there: never registered (§9.2 superseded). */
+ | "superseded"
+/** The Resource refused the record (reported, not repeated, §7.1). */
+ | "refused"
+/** This installation may not act there (§5.3 step 10): left to reconciliation. */
+ | "not-authorized"
+/** The coordinator does not advertise identity-01 (W §37). */
+ | "unsupported"
+/** The coordinator could not be reached: left to reconciliation. */
+ | "unreachable"
+/** The Resource is forked (§9.7). */
+ | "conflict";
+export interface RegistrationResult {
+    readonly resource: ResourceId;
+    readonly status: RegistrationStatus;
+    readonly code?: string;
+    readonly keys?: KeyDelivery;
+}
+export interface RegisterTarget {
+    readonly resource: ResourceId;
+    /** The coordinator URL (the roster entry's coordinator, or the chain's route). */
+    readonly url: string;
+}
+/**
+ * Registers a device in Resources (§5.3 step 10, §7.2, §7.3, §7.1 step
+ * 2): `DEVICE_GRANT {R, chain}` on each target where this installation may
+ * act, then a Key Package of every epoch DEK it holds there to the device,
+ * each recorded in the ledger. One journaled operation; each Resource is
+ * a phase classified by §9.2 before anything is proposed, so a
+ * registration that exists by another hand is `complete` and is not
+ * proposed again. Resources this installation cannot reach are listed.
+ */
+export declare function registerDevice(options: FlowOptions & {
+    readonly chain: CertificateChain;
+    readonly targets: readonly RegisterTarget[];
+    /** Resume this operation instead of starting one. */
+    readonly operation?: string;
+}): Promise<{
+    readonly operation: string;
+    readonly results: readonly RegistrationResult[];
+}>;
+//# sourceMappingURL=devices.d.ts.map