@openlfcp/client 0.2.2 → 0.3.1

package/dist/identity/pairing-request.js

@@ -0,0 +1,422 @@
+import { bytesEqual, fromBase64url, fromHex, hash32, principalId, resourceId, secureRandom, toBase64url, toHex, } from "@openlfcp/core";
+import { activeDevice, certificateChain, DEVICE_KIND, decodeInviteSecret, deviceFingerprint, encodeInviteSecret, encodePrincipalDescriptor, invitationPrincipal, pairingDeviceSigner, parseDataUnit, parseDeviceCertificate, parsePairingUri, revocationOf, } from "@openlfcp/wire";
+import { fetchDeks, genesisOwner, IdentityConflict, loadIdentityDocument, runUnitPhase, sealIdentityUnit, syncChain, } from "./context.js";
+import { IDENTITY_PROFILE, principalRefOf, resourceRef, } from "./document.js";
+import { newOperationId, OperationJournal, pairingSecretRef, phaseOf } from "./journal.js";
+import { ChannelPool, IDENTITY_EXTENSION, IdentityRefused, IdentityUnavailable, } from "./network.js";
+import { setLocalIdentityResource } from "./resource.js";
+/** §5.3 steps 2–3. */
+export async function requestPairing(o) {
+    let link;
+    let J;
+    try {
+        link = parsePairingUri(typeof o.link === "string" ? o.link : o.link.reveal());
+        J = pairingDeviceSigner(link);
+    }
+    catch (e) {
+        return { kind: "invalid-link", reason: e instanceof Error ? e.message : String(e) };
+    }
+    const I = link.identityResourceId;
+    const url = link.endpoints[0];
+    const B = o.installation.signer.descriptor;
+    const pool = new ChannelPool(o.network);
+    const journal = new OperationJournal(o.storage);
+    let operation;
+    try {
+        // A request already journaled for this session and installation is resumed (§9.1).
+        const open = (await journal.list({ kind: "pairing-request", status: "open" })).find((op) => op.intent.pairingDevice === toHex(J.descriptor.principalId) &&
+            op.intent.device === toHex(B.principalId));
+        if (open !== undefined) {
+            operation = open.id;
+            const sent = await sendRequest(o, pool, open.id);
+            if (sent !== "committed-own")
+                return { kind: "refused", operation, code: sent.code };
+            return {
+                kind: "requested",
+                operation,
+                identity: I,
+                fingerprint: deviceFingerprint(B.principalId),
+            };
+        }
+        const channel = await pool.get(J, url);
+        const chain = await syncChain(o.storage, channel, I);
+        const R = genesisOwner(chain);
+        if (chain.state.dataProfile !== IDENTITY_PROFILE)
+            return { kind: "not-a-session", reason: "the Resource is not an Identity Resource" };
+        const j = activeDevice(chain.state, J.descriptor.principalId);
+        if (j === undefined || j.kind !== DEVICE_KIND.PAIRING || !bytesEqual(j.root, R))
+            return {
+                kind: "not-a-session",
+                reason: "the link's device is not an active pairing device of the owner",
+            };
+        const pairing = { signer: J, agreement: link.secret.agreementKey };
+        const deks = await fetchDeks(o.storage, o.secrets, channel, chain, pairing);
+        const doc = o.document(I, R);
+        await loadIdentityDocument({ channel, chain, deks, doc });
+        if (!doc.initialized())
+            return {
+                kind: "missing-material",
+                missing: deks.size === 0 ? ["the DEKs of the Identity Resource"] : ["the root's unit 1"],
+            };
+        // Step 3: the candidates B may be registered in, persisted before the request.
+        const chosen = new Set((o.scope ?? []).map((r) => resourceRef(r)));
+        const offered = [...doc.roster()].filter(([ref, e]) => e.archived !== true && ref !== resourceRef(I));
+        if (o.sections !== undefined) {
+            const unknown = [];
+            for (const name of o.sections) {
+                const hits = offered.filter(([, e]) => e.name === name);
+                if (hits.length === 1)
+                    chosen.add(hits[0][0]);
+                else
+                    unknown.push(name);
+            }
+            if (unknown.length > 0)
+                return {
+                    kind: "unknown-sections",
+                    unknown,
+                    available: offered
+                        .map(([, e]) => e.name)
+                        .filter((n) => n !== undefined)
+                        .sort(),
+                };
+        }
+        const candidates = offered
+            .filter(([ref]) => o.kind === 0 || chosen.has(ref))
+            .map(([ref, e]) => ({
+            resource: toHex(fromBase64url(ref)),
+            url: e.coordinator,
+            profile: e.profile,
+            ...(e.name === undefined ? {} : { name: e.name }),
+        }));
+        const secret = encodeInviteSecret(link.secret);
+        try {
+            await o.secrets.put(pairingSecretRef(J.descriptor.principalId), secret);
+        }
+        finally {
+            secret.fill(0);
+        }
+        // The whole request is durable before anything is sent (§9.1): a restart
+        // resumes it from the journal (completePairing), never a second request.
+        operation = newOperationId("pairing-request", secureRandom(8));
+        await journal.begin({
+            id: operation,
+            kind: "pairing-request",
+            createdAt: o.now(),
+            intent: {
+                identity: toHex(I),
+                url,
+                root: toHex(R),
+                pairingDevice: toHex(J.descriptor.principalId),
+                device: toHex(B.principalId),
+                kind: o.kind,
+                label: o.label,
+                candidates,
+                request: {
+                    descriptor: toBase64url(encodePrincipalDescriptor(B)),
+                    pairing: principalRefOf(J.descriptor.principalId),
+                    label: o.label,
+                    kind: o.kind,
+                    ...(o.kind === 1
+                        ? { scope: candidates.map((c) => toBase64url(fromHex(c.resource))) }
+                        : {}),
+                    ...(o.platform === undefined ? {} : { platform: o.platform }),
+                    ...(o.requestedAt === undefined ? {} : { requested_at: o.requestedAt }),
+                },
+            },
+        });
+        const sent = await sendRequest(o, pool, operation);
+        if (sent !== "committed-own")
+            return { kind: "refused", operation, code: sent.code };
+        return {
+            kind: "requested",
+            operation,
+            identity: I,
+            fingerprint: deviceFingerprint(B.principalId),
+        };
+    }
+    catch (e) {
+        if (e instanceof IdentityUnavailable ||
+            e instanceof IdentityRefused ||
+            e instanceof IdentityConflict)
+            return {
+                kind: "unavailable",
+                ...(operation === undefined ? {} : { operation }),
+                reason: e.message,
+            };
+        throw e;
+    }
+    finally {
+        pool.closeAll();
+    }
+}
+/** The pairing device of a journaled request, from the SecretStore (§9.8). */
+async function pairingSigner(o, J) {
+    const bytes = await o.secrets.get(pairingSecretRef(J));
+    if (bytes === undefined)
+        return undefined;
+    try {
+        const secret = decodeInviteSecret(bytes);
+        return {
+            signer: { key: secret.signingKey, descriptor: invitationPrincipal(secret) },
+            agreement: secret.agreementKey,
+        };
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+/**
+ * Sends the journaled request as the pairing device: the journaled exact
+ * bytes when they exist, else a unit built from the journaled request at the
+ * next sequence the pairing device has on the coordinator (§5.3 step 3).
+ */
+async function sendRequest(o, pool, operation) {
+    const journal = new OperationJournal(o.storage);
+    const op = await journal.load(operation);
+    if (phaseOf(op, "request")?.state === "committed-own")
+        return "committed-own";
+    const I = resourceId(fromHex(op.intent.identity));
+    const R = principalId(fromHex(op.intent.root));
+    const pairing = await pairingSigner(o, principalId(fromHex(op.intent.pairingDevice)));
+    if (pairing === undefined)
+        return { code: "PAIRING_SECRET_GONE" };
+    const channel = await pool.get(pairing.signer, op.intent.url);
+    const B = principalId(fromHex(op.intent.device));
+    const unit = await runUnitPhase(channel, journal, operation, {
+        id: "request",
+        resource: I,
+        // A request refused as stale (I rotated before it arrived) is written again
+        // in the current epoch (W §19.1); its refused bytes stay in the phase.
+        rebuildOn: ["STALE_DATA_EPOCH"],
+        build: async () => {
+            // Never the sequence of a unit already signed for this request (W §26.2).
+            const signed = phaseOf(await journal.load(operation), "request")?.bytes;
+            const used = signed === undefined ? 0n : parseDataUnit(fromHex(signed)).payload.actorSeq;
+            const chain = await syncChain(o.storage, channel, I);
+            const deks = await fetchDeks(o.storage, o.secrets, channel, chain, pairing);
+            const doc = o.document(I, R);
+            const load = await loadIdentityDocument({ channel, chain, deks, doc });
+            const previous = load.latest.get(toHex(pairing.signer.descriptor.principalId));
+            return sealIdentityUnit({
+                storage: o.storage,
+                chain,
+                deks,
+                signer: pairing.signer,
+                doc,
+                latest: load.latest,
+                // J may be used by another installation: the next sequence after the one it sees (§5.3).
+                seq: ((previous?.seq ?? 0n) > used ? (previous?.seq ?? 0n) : used) + 1n,
+                intents: [
+                    {
+                        intent: "request.put",
+                        key: principalRefOf(B),
+                        entry: op.intent.request,
+                    },
+                ],
+            });
+        },
+    });
+    return unit.state === "committed-own" ? "committed-own" : { code: unit.code ?? "refused" };
+}
+/** The accepted DEVICE_GRANT leaves naming `device` in a chain's history, oldest first. */
+function leavesOf(chain, device) {
+    return chain.records
+        .filter((r) => r.body.type === "DEVICE_GRANT" &&
+        bytesEqual(r.body.chain.leaf.payload.device.principalId, device))
+        .map((r) => r.body.chain);
+}
+const sameSet = (a, b) => a.length === b.length && a.every((x) => b.includes(x));
+export function candidateEvidence(chain, device, digest, result) {
+    const leaves = leavesOf(chain, device);
+    const proven = leaves.some((l) => bytesEqual(l.leaf.payloadDigest, digest));
+    const d = chain.state.devices.get(toHex(device));
+    const active = d?.registered === true && activeDevice(chain.state, device) !== undefined;
+    const same = d !== undefined &&
+        d.kind === result.kind &&
+        sameSet(d.mask.map(String), result.mask.map(String)) &&
+        sameSet(d.scope.map(toHex), result.scope.map(toHex));
+    return Object.freeze({
+        leaves: Object.freeze(leaves.map((l) => l.leaf.id)),
+        proven,
+        registration: active ? "active" : "pending",
+        usable: proven && active && same,
+    });
+}
+/**
+ * §5.3 steps 8 and 11: learns the session's result and the status of
+ * every candidate. Resumable at any point from the persisted candidates
+ * (and while `J` is active, from the link's secret in the SecretStore).
+ */
+export async function completePairing(o) {
+    const journal = new OperationJournal(o.storage);
+    let op = await journal.load(o.operation);
+    const I = resourceId(fromHex(op.intent.identity));
+    const R = principalId(fromHex(op.intent.root));
+    const Jid = principalId(fromHex(op.intent.pairingDevice));
+    const B = o.installation.signer;
+    const D = B.descriptor.principalId;
+    const kind = op.intent.kind;
+    const pool = new ChannelPool(o.network);
+    try {
+        // Step 8: the session's state first, from J's view of I (W §41 after its
+        // revocation): a closed session's result is never hidden by a failed send.
+        if (op.intent.result === undefined) {
+            const bytes = await o.secrets.get(pairingSecretRef(Jid));
+            if (bytes === undefined)
+                return { kind: "unknown", reason: "the pairing secret is gone" };
+            let J;
+            try {
+                const secret = decodeInviteSecret(bytes);
+                J = { key: secret.signingKey, descriptor: invitationPrincipal(secret) };
+            }
+            finally {
+                bytes.fill(0);
+            }
+            let chain;
+            try {
+                chain = await syncChain(o.storage, await pool.get(J, op.intent.url), I);
+            }
+            catch (e) {
+                if (e instanceof IdentityRefused)
+                    return {
+                        kind: "unknown",
+                        reason: "the pairing device can no longer read and no proof is served",
+                    };
+                throw e;
+            }
+            const r = revocationOf(chain.state, R, Jid);
+            if (r === undefined) {
+                // J is active: a request that never reached the coordinator is sent now,
+                // from the journal, or written again in the current epoch (§9.1).
+                if (phaseOf(op, "request")?.state !== "committed-own") {
+                    const sent = await sendRequest(o, pool, o.operation);
+                    if (sent !== "committed-own")
+                        return { kind: "unknown", reason: `the request was refused: ${sent.code}` };
+                }
+                return { kind: "waiting" };
+            }
+            if (r.reason === 3n && r.approval !== null)
+                op = await journal.updateIntent(o.operation, {
+                    result: "approved",
+                    digest: toHex(r.approval),
+                });
+            else {
+                await journal.updateIntent(o.operation, { result: "rejected" });
+                await journal.setStatus(o.operation, "abandoned");
+                await o.secrets.delete(pairingSecretRef(Jid));
+                return { kind: "rejected" };
+            }
+            await o.secrets.delete(pairingSecretRef(Jid));
+        }
+        if (op.intent.result === "rejected")
+            return { kind: "rejected" };
+        const digest = hash32(fromHex(op.intent.digest));
+        const candidates = op.intent.candidates.map((c) => ({
+            resource: resourceId(fromHex(c.resource)),
+            url: c.url,
+            ...(c.name === undefined ? {} : { name: c.name }),
+        }));
+        // A personal B is registered in I itself; a service B only in its candidates.
+        const places = kind === 0 ? [{ resource: I, url: op.intent.url }, ...candidates] : candidates;
+        let certificate = op.intent.certificate === undefined
+            ? null
+            : certificateChain(op.intent.certificate.map((c) => parseDeviceCertificate(fromHex(c))), R);
+        let foreign = 0;
+        const seen = new Map();
+        for (const p of places) {
+            try {
+                const channel = await pool.get(B, p.url);
+                if (!channel.extensions.includes(IDENTITY_EXTENSION)) {
+                    seen.set(toHex(p.resource), "unsupported");
+                    continue;
+                }
+                const chain = await syncChain(o.storage, channel, p.resource);
+                seen.set(toHex(p.resource), { chain });
+                for (const leaf of leavesOf(chain, D)) {
+                    if (!bytesEqual(leaf.leaf.payloadDigest, digest)) {
+                        foreign++;
+                        continue;
+                    }
+                    // The first verified certificate decides (§5.3 step 8).
+                    if (certificate === null &&
+                        bytesEqual(leaf.root, R) &&
+                        bytesEqual(leaf.leaf.payload.root, R) &&
+                        bytesEqual(leaf.leaf.payload.device.principalId, D)) {
+                        certificate = leaf;
+                        op = await journal.updateIntent(o.operation, {
+                            certificate: leaf.certificates.map((c) => toHex(c.signed.bytes)),
+                        });
+                        if (kind === 0)
+                            await setLocalIdentityResource(o.storage, I);
+                    }
+                }
+            }
+            catch (e) {
+                if (e instanceof IdentityUnavailable)
+                    seen.set(toHex(p.resource), "unreachable");
+                else if (e instanceof IdentityRefused)
+                    seen.set(toHex(p.resource), "closed");
+                else if (e instanceof IdentityConflict)
+                    seen.set(toHex(p.resource), "unreachable");
+                else
+                    throw e;
+            }
+        }
+        if (certificate === null)
+            // "approved, waiting for registration": no candidate's outcome is known yet.
+            return { kind: "approved", certificate: null, candidates: [], foreignCertificates: foreign };
+        const result = certificate.leaf.payload;
+        const out = [];
+        for (const p of places) {
+            const s = seen.get(toHex(p.resource));
+            const status = async () => {
+                if (result.kind !== DEVICE_KIND.PERSONAL &&
+                    !result.scope.some((r) => bytesEqual(r, p.resource)))
+                    return bytesEqual(p.resource, I) ? "pending-registration" : "not-granted";
+                if (s === "unreachable" || s === undefined)
+                    return "unreachable";
+                if (s === "unsupported")
+                    return "unsupported";
+                if (s === "closed")
+                    return "pending-registration";
+                const evidence = candidateEvidence(s.chain, D, digest, result);
+                if (evidence.registration === "pending")
+                    return "pending-registration";
+                if (!evidence.usable)
+                    return "unproven";
+                const channel = await pool.get(B, p.url);
+                const deks = await fetchDeks(o.storage, o.secrets, channel, s.chain, o.installation);
+                return [...s.chain.state.epochs.keys()].every((e) => deks.has(e))
+                    ? "ready"
+                    : "waiting-for-keys";
+            };
+            const named = p.name === undefined ? {} : { name: p.name };
+            try {
+                out.push({ resource: p.resource, status: await status(), ...named });
+            }
+            catch (e) {
+                if (e instanceof IdentityUnavailable || e instanceof IdentityRefused)
+                    out.push({ resource: p.resource, status: "unreachable", ...named });
+                else
+                    throw e;
+            }
+        }
+        if (out.every((c) => c.status === "ready" || c.status === "not-granted"))
+            await journal.setStatus(o.operation, "done");
+        return {
+            kind: "approved",
+            certificate,
+            candidates: Object.freeze(out),
+            foreignCertificates: foreign,
+        };
+    }
+    catch (e) {
+        if (e instanceof IdentityUnavailable || e instanceof IdentityConflict)
+            return { kind: "unavailable", reason: e.message };
+        throw e;
+    }
+    finally {
+        pool.closeAll();
+    }
+}
+//# sourceMappingURL=pairing-request.js.map

package/dist/identity/pairing.d.ts

@@ -0,0 +1,225 @@
+import { type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type CertificateChain, type Signer } from "@openlfcp/wire";
+import { type FlowOptions, type MaskPreset, type RegistrationResult } from "./devices.js";
+import { type LinearChain } from "./phases.js";
+import { type IdentityFlowOptions } from "./resource.js";
+import type { RotationOutcome } from "./rotation.js";
+/**
+ * Pairing a new installation, the managing side `A` (IDENTITY-PROFILE-01
+ * §5.3 steps 1, 4–7, 9 and 10): a pairing device `J` registered in the
+ * Identity Resource for one session, the request it carries validated and
+ * checked against the complete future certificate chain, then the two
+ * phases: consume `J` with the approved payload's digest, sign and register
+ * exactly that payload. Every phase is journaled and classified by §9.2, so
+ * a crash or a lost answer resumes without signing anything else; a
+ * pairing session yields at most one approved payload.
+ */
+/** A bearer link (§5.2): its text is revealed on demand and never logged. */
+export declare class PairingLinkText {
+    #private;
+    constructor(uri: string);
+    /** The lfcp://pair URI with its #secret= fragment. Show it to the human; never log it. */
+    reveal(): string;
+    toJSON(): string;
+    toString(): string;
+}
+export type PairingSessionResult = {
+    readonly kind: "created";
+    readonly session: string;
+    readonly pairingDevice: PrincipalId;
+    readonly link: PairingLinkText;
+}
+/** §5.3 step 1: the root already has 32 live devices in I; revoke one first. */
+ | {
+    readonly kind: "limit";
+    readonly reason: string;
+}
+/** A lacks the root's unit 1 or a DEK of I: no link (§5.3 step 1). */
+ | {
+    readonly kind: "missing-material";
+    readonly missing: readonly string[];
+}
+/** This installation is not the root or an active managing device of it. */
+ | {
+    readonly kind: "not-authorized";
+    readonly reason: string;
+} | {
+    readonly kind: "refused";
+    readonly code: string;
+} | {
+    readonly kind: "conflict";
+} | {
+    readonly kind: "unavailable";
+    readonly session?: string;
+    readonly reason: string;
+};
+/**
+ * §5.3 step 1: creates a pairing device `J` (kind 2, mask {1, 2}, scope
+ * [I]), registers it in `I`, seals to it the DEK of every epoch of `I`, and
+ * returns the link. Before anything is committed `A` must hold, verified,
+ * the root's unit 1 and the DEK of every epoch of `I` (otherwise no link),
+ * and the DEVICE_GRANT must fit the root's 32 live devices (W §17.4 rule 8).
+ */
+export declare function createPairingSession(o: IdentityFlowOptions & {
+    readonly endpoints?: readonly string[];
+}): Promise<PairingSessionResult>;
+/**
+ * §5.3 step 1 after a crash before the link was shown: completes the
+ * registration of `J` and its packages from the journal, then returns the
+ * link again.
+ */
+export declare function resumePairingSession(o: IdentityFlowOptions, session: string): Promise<PairingSessionResult>;
+/** A pairing request `A` may show (§5.3 step 4). */
+export interface PairingReview {
+    readonly session: string;
+    /** `requests[k]`: the PrincipalRef of `D_B`. */
+    readonly requestKey: string;
+    readonly device: PrincipalId;
+    /** base64url of the exact descriptor bytes. */
+    readonly descriptor: string;
+    readonly label: string;
+    readonly platform?: string;
+    readonly kind: 0 | 1;
+    /** The requested scope (kind 1), the Identity Resource already removed. */
+    readonly requestedScope: readonly ResourceId[];
+    /** §5.2 device fingerprint of `D_B`, for the human to compare with B's screen. */
+    readonly fingerprint: string;
+    /** Each preset of §5.4 for the request's kind, and whether the future chain passes (§5.3 step 4). */
+    readonly presets: readonly {
+        readonly preset: MaskPreset;
+        readonly offered: boolean;
+        readonly reason?: string;
+    }[];
+    /**
+     * The hashes of the changes that wrote the request, in causal order: the
+     * request change hash §5.3 step 4 journals with the approval.
+     */
+    readonly requestChanges: readonly string[];
+    /** The confirmed tuple: when the entry or any change to it differs, the confirmation is asked again. */
+    readonly tuple: string;
+}
+/** §5.3 step 4: the valid requests of a session, each with the presets whose future chain passes. */
+export declare function pairingRequests(o: IdentityFlowOptions & {
+    readonly session: string;
+}): Promise<readonly PairingReview[]>;
+export type ApprovalResult = {
+    readonly kind: "approved";
+    readonly operation: string;
+    readonly device: PrincipalId;
+    readonly chain: CertificateChain;
+    /** §5.3 step 10: the Resources of the roster (or the approved scope). */
+    readonly registrations: readonly RegistrationResult[];
+    /** §5.3 step 9: the consumed pairing device was a reader of I (§8.4). */
+    readonly rotation: RotationOutcome;
+}
+/** The entry changed since the human confirmed it: ask again (§5.3 step 4). */
+ | {
+    readonly kind: "reconfirm";
+    readonly review: PairingReview | undefined;
+}
+/** The preset's future chain does not pass on the current head (§5.3 step 4). */
+ | {
+    readonly kind: "infeasible";
+    readonly reason: string;
+}
+/** The session was consumed by another approval or cancelled: nothing is signed (§9.2). */
+ | {
+    readonly kind: "superseded";
+    readonly operation: string;
+}
+/** Phase 2 meets the 32-device limit: retry after a revocation; the approval stays consumed (§5.3 step 6). */
+ | {
+    readonly kind: "limit";
+    readonly operation: string;
+} | {
+    readonly kind: "refused";
+    readonly operation: string;
+    readonly code: string;
+}
+/**
+ * Approved in the chain (phases 1 and 2, keys, rotation and registrations
+ * as for `approved`), but the coordinator refused the document unit of
+ * §5.3 step 6 with `code`: the device entry is not written and the request
+ * not removed. The operation stays open; resumeApproval writes the unit
+ * again on the current state.
+ */
+ | {
+    readonly kind: "document-incomplete";
+    readonly operation: string;
+    readonly device: PrincipalId;
+    readonly chain: CertificateChain;
+    readonly registrations: readonly RegistrationResult[];
+    readonly rotation: RotationOutcome;
+    readonly code: string;
+} | {
+    readonly kind: "conflict";
+} | {
+    readonly kind: "unavailable";
+    readonly operation?: string;
+    readonly reason: string;
+};
+/**
+ * §5.3 steps 4–7 and 10: approves the confirmed request with a preset
+ * (and, for a service device, a scope within the requested one). The
+ * complete certificate payload and its digest are journaled before
+ * phase 1; phase 2 signs exactly that payload.
+ */
+export declare function approvePairing(o: IdentityFlowOptions & {
+    readonly review: PairingReview;
+    readonly preset: MaskPreset;
+    /** Service only: the approved scope, a subset of the requested one. */
+    readonly scope?: readonly ResourceId[];
+    /** RFC 3339 UTC for `devices[...].added_at`. */
+    readonly addedAt?: string;
+}): Promise<ApprovalResult>;
+/** Phase 1 (§5.3 step 5): `DEVICE_REVOKE {R, J, 3, digest}` on the chain's head. */
+export declare const consumeRecord: (chain: LinearChain, signer: Signer, root: PrincipalId, pairing: PrincipalId, digest: Hash32) => Uint8Array;
+/** Phase 2 (§5.3 step 6): `DEVICE_GRANT {R, chain_B, 2: J}` on the chain's head. */
+export declare const approvedGrantRecord: (chain: LinearChain, signer: Signer, root: PrincipalId, device: CertificateChain, pairing: PrincipalId) => Uint8Array;
+/** §5.3 step 9: `DEVICE_REVOKE {R, J, 0}` on the chain's head. */
+export declare const cancelRecord: (chain: LinearChain, signer: Signer, root: PrincipalId, pairing: PrincipalId) => Uint8Array;
+/** Resumes a journaled approval from its next phase (§9.1: "If A crashes after step 5 …"). */
+export declare function resumeApproval(o: IdentityFlowOptions, operation: string): Promise<ApprovalResult>;
+export type CancelResult = {
+    readonly kind: "cancelled";
+    readonly rotation: RotationOutcome;
+}
+/**
+ * Cancelled in the chain, but the coordinator refused the unit that
+ * deletes the rejected request (§5.3 step 4) with `code`: the request
+ * entry stays. The session stays open; cancelPairing with the same
+ * `reject` writes the unit again.
+ */
+ | {
+    readonly kind: "document-incomplete";
+    readonly rotation: RotationOutcome;
+    readonly code: string;
+}
+/** The session was consumed by an approval: not cancelled (§9.2 Cancel: superseded). */
+ | {
+    readonly kind: "consumed";
+} | {
+    readonly kind: "refused";
+    readonly code: string;
+} | {
+    readonly kind: "conflict";
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+/**
+ * §5.3 step 9 (rejection, timeout, cancel): `DEVICE_REVOKE {R, J, 0}`.
+ * With `reject`, the request entry is deleted first (step 4: a request the
+ * human does not confirm is rejected).
+ */
+export declare function cancelPairing(o: IdentityFlowOptions & {
+    readonly session: string;
+    readonly reject?: string;
+}): Promise<CancelResult>;
+/** Open pairing sessions of this installation, oldest first. */
+export declare function openPairingSessions(o: Pick<FlowOptions, "storage">): Promise<{
+    session: string;
+    identity: ResourceId;
+    pairingDevice: PrincipalId;
+}[]>;
+//# sourceMappingURL=pairing.d.ts.map