@openlfcp/client 0.2.2 → 0.3.1

package/dist/identity/journal.js

@@ -0,0 +1,202 @@
+import { fromHex, toHex, } from "@openlfcp/core";
+import { exportSecretKeyBytes, importResourceDEK } from "@openlfcp/crypto";
+import { secretRef } from "@openlfcp/storage";
+const OP_PREFIX = "identity-op:";
+const LEDGER_PREFIX = "identity-ledger:";
+const SECRETS_IN_JOURNAL = /secret|seed|private|dek/i;
+function checkNoSecrets(value, path = "intent") {
+    if (value === null || typeof value !== "object")
+        return;
+    for (const [k, v] of Object.entries(value)) {
+        // §9.8: the journal never names a secret field; secrets go to the SecretStore.
+        if (SECRETS_IN_JOURNAL.test(k) && k !== "dekRef")
+            throw new Error(`a journal row must not hold secrets (${path}.${k}, §9.8)`);
+        checkNoSecrets(v, `${path}.${k}`);
+    }
+}
+/** The durable operation journal (§9.1). */
+export class OperationJournal {
+    #storage;
+    constructor(storage) {
+        this.#storage = storage;
+    }
+    async #put(op) {
+        checkNoSecrets(op.intent);
+        const result = await this.#storage.commit([
+            { op: "put-local-mark", key: `${OP_PREFIX}${op.id}`, value: JSON.stringify(op) },
+        ]);
+        if (!result.ok)
+            throw new Error(`the operation journal was not stored: ${result.reason}`);
+    }
+    /** Persists a new operation before any of its records is sent. */
+    async begin(op) {
+        const row = Object.freeze({
+            v: 1,
+            status: "open",
+            phases: [],
+            ...op,
+        });
+        if ((await this.get(op.id)) !== undefined)
+            throw new Error(`operation ${op.id} is already journaled`);
+        await this.#put(row);
+        return row;
+    }
+    async get(id) {
+        const value = await this.#storage.localMarks.get(`${OP_PREFIX}${id}`);
+        return value === undefined ? undefined : JSON.parse(value);
+    }
+    /** Every journaled operation, optionally of one kind and status, oldest first. */
+    async list(filter = {}) {
+        return (await this.#storage.localMarks.list(OP_PREFIX))
+            .map((m) => JSON.parse(m.value))
+            .filter((o) => (filter.kind === undefined || o.kind === filter.kind) &&
+            (filter.status === undefined || o.status === filter.status))
+            .sort((a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : 1));
+    }
+    /** Writes the phase (replacing the one with its ID), durably. */
+    async putPhase(id, phase) {
+        const op = await this.load(id);
+        const phases = op.phases.some((p) => p.id === phase.id)
+            ? op.phases.map((p) => (p.id === phase.id ? phase : p))
+            : [...op.phases, phase];
+        const next = Object.freeze({ ...op, phases: Object.freeze(phases) });
+        await this.#put(next);
+        return next;
+    }
+    /** Updates the intent with more public facts (e.g. the session's record IDs). */
+    async updateIntent(id, patch) {
+        const op = await this.load(id);
+        const next = Object.freeze({ ...op, intent: Object.freeze({ ...op.intent, ...patch }) });
+        await this.#put(next);
+        return next;
+    }
+    async setStatus(id, status) {
+        const op = await this.load(id);
+        const next = Object.freeze({ ...op, status });
+        await this.#put(next);
+        return next;
+    }
+    /** Removes a finished operation's row. */
+    async remove(id) {
+        await this.#storage.commit([{ op: "put-local-mark", key: `${OP_PREFIX}${id}`, value: null }]);
+    }
+    async load(id) {
+        const op = await this.get(id);
+        if (op === undefined)
+            throw new Error(`operation ${id} is not journaled`);
+        return op;
+    }
+}
+/** The phase `id` of `op`, if journaled. */
+export const phaseOf = (op, id) => op.phases.find((p) => p.id === id);
+const pendingKey = (resource, epoch, recipient) => `identity-package-pending:${toHex(resource)}:${epoch}:${toHex(recipient)}`;
+const ledgerKey = (resource, epoch, recipient) => `${LEDGER_PREFIX}${toHex(resource)}:${epoch}:${toHex(recipient)}`;
+/**
+ * The package ledger (§9.5): every Key Package this installation sent, as
+ * `(resource, epoch, recipient, package ID)`. It drives reconciliation's
+ * key step (§7.1 step 3); delivery is never inferred from the absence of a
+ * complaint, and a cleared entry causes a re-send.
+ */
+export class PackageLedger {
+    #storage;
+    constructor(storage) {
+        this.#storage = storage;
+    }
+    /** Records an acknowledged package and drops its pending bytes, in one commit. */
+    async record(entry) {
+        const result = await this.#storage.commit([
+            {
+                op: "put-local-mark",
+                key: ledgerKey(entry.resource, entry.epoch, entry.recipient),
+                value: toHex(entry.packageId),
+            },
+            {
+                op: "put-local-mark",
+                key: pendingKey(entry.resource, entry.epoch, entry.recipient),
+                value: null,
+            },
+        ]);
+        if (!result.ok)
+            throw new Error(`the package ledger was not stored: ${result.reason}`);
+    }
+    /** The exact bytes of a package sent but not yet acknowledged (§9.1). */
+    async pending(resource, epoch, recipient) {
+        const v = await this.#storage.localMarks.get(pendingKey(resource, epoch, recipient));
+        return v === undefined ? undefined : fromHex(v);
+    }
+    /** Persists a package's exact bytes before it is sent. */
+    async putPending(resource, epoch, recipient, bytes) {
+        const result = await this.#storage.commit([
+            { op: "put-local-mark", key: pendingKey(resource, epoch, recipient), value: toHex(bytes) },
+        ]);
+        if (!result.ok)
+            throw new Error(`the pending package was not stored: ${result.reason}`);
+    }
+    async has(resource, epoch, recipient) {
+        return ((await this.#storage.localMarks.get(ledgerKey(resource, epoch, recipient))) !== undefined);
+    }
+    /** Every entry for `resource`. */
+    async list(resource) {
+        return (await this.#storage.localMarks.list(`${LEDGER_PREFIX}${toHex(resource)}:`)).map((m) => {
+            const [, r, e, p] = m.key.split(":");
+            return Object.freeze({
+                resource: fromHex(r),
+                epoch: BigInt(e),
+                recipient: fromHex(p),
+                packageId: fromHex(m.value),
+            });
+        });
+    }
+    /**
+     * "Re-send keys" (§7.1 step 3): forgets every package sent to
+     * `recipient`, in `resource` or everywhere, so the next reconciliation
+     * re-seals them.
+     */
+    async clear(recipient, resource) {
+        const prefix = resource === undefined ? LEDGER_PREFIX : `${LEDGER_PREFIX}${toHex(resource)}:`;
+        const suffix = `:${toHex(recipient)}`;
+        const keys = (await this.#storage.localMarks.list(prefix))
+            .map((m) => m.key)
+            .filter((k) => k.endsWith(suffix));
+        if (keys.length === 0)
+            return 0;
+        const result = await this.#storage.commit(keys.map((key) => ({ op: "put-local-mark", key, value: null })));
+        if (!result.ok)
+            throw new Error(`the package ledger was not updated: ${result.reason}`);
+        return keys.length;
+    }
+}
+/**
+ * The SecretStore slot of a DEK generated for a KEY_EPOCH that is not
+ * committed yet (§9.1: persisted before the record is sent). It is not the
+ * epoch's DEK slot: until the record is accepted, another rotator may
+ * commit that epoch number with another DEK.
+ */
+export const pendingDekRef = (resource, operation) => secretRef("resource-dek", `${toHex(resource)}.pending.${operation}`);
+/** The SecretStore slot of a pairing device's invite-secret (§5.2, §9.8). */
+export const pairingSecretRef = (pairingDevice) => secretRef("invitation-secret", `pairing.${toHex(pairingDevice)}`);
+export async function putPendingDek(secrets, resource, operation, dek) {
+    const bytes = exportSecretKeyBytes(dek);
+    try {
+        await secrets.put(pendingDekRef(resource, operation), bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+export async function getPendingDek(secrets, resource, operation) {
+    const bytes = await secrets.get(pendingDekRef(resource, operation));
+    if (bytes === undefined)
+        return undefined;
+    try {
+        return importResourceDEK(bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+/** A fresh, unique operation ID. */
+export function newOperationId(kind, random) {
+    return `${kind}.${toHex(random)}`;
+}
+//# sourceMappingURL=journal.js.map

package/dist/identity/network.d.ts

@@ -0,0 +1,88 @@
+import { type ControlRecordId, type DataEpoch, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type ControlHeadRef, type DataRange, type LiveActorHave, type Signer } from "@openlfcp/wire";
+import { type WebSocketFactory } from "../connection.js";
+/**
+ * The network port of the identity flows (IDENTITY-PROFILE-01 §§5–9).
+ *
+ * Every flow talks to coordinators through an IdentityChannel: one
+ * authenticated session as one Principal (the installation's own, a
+ * pairing device's, an Invitation Principal's) to one coordinator. The
+ * port keeps the flows independent of the transport: connectionNetwork()
+ * runs it over LfcpConnection, tests run it against an in-memory
+ * coordinator. A transport failure throws IdentityUnavailable and leaves
+ * every journal as it is, so the flow resumes later (§9); a NACK is an
+ * answer, returned to the flow.
+ */
+/** The coordinator's answer to an upload (CONTROL_PUT, KEY_PACKAGE_PUT, DATA_PUT, RESOURCE_HOST). */
+export type IdentityAnswer = {
+    readonly kind: "ack";
+} | {
+    readonly kind: "nack";
+    readonly code: string;
+    /** For CONTROL_HEAD_MISMATCH: the coordinator's head, when it named one (§47). */
+    readonly head?: ControlRecordId;
+};
+export type OpenAnswer = {
+    readonly kind: "opened";
+    readonly heads: readonly ControlHeadRef[];
+    readonly haves: readonly LiveActorHave[];
+} | {
+    readonly kind: "nack";
+    readonly code: string;
+};
+export interface IdentityChannel {
+    /** READY's extensions (§37); `identity-01` when the server supports device records. */
+    readonly extensions: readonly string[];
+    /** RESOURCE_HOST with the exact Genesis bytes (§39). */
+    host(genesis: Uint8Array): Promise<IdentityAnswer>;
+    /** RESOURCE_OPEN without subscriptions (§41). */
+    open(resource: ResourceId): Promise<OpenAnswer>;
+    /** CONTROL_GET from `start` to the end (§45); throws IdentityRefused on a NACK. */
+    control(resource: ResourceId, start: bigint): Promise<readonly Uint8Array[]>;
+    /** CONTROL_PUT with compare-and-swap (§47). */
+    putControl(resource: ResourceId, expectedHead: ControlRecordId, record: Uint8Array): Promise<IdentityAnswer>;
+    /** KEY_PACKAGE_GET (§52: at most 256 epochs); throws IdentityRefused on a NACK. */
+    keyPackages(resource: ResourceId, recipient: PrincipalId, epochs: readonly DataEpoch[]): Promise<readonly Uint8Array[]>;
+    /** KEY_PACKAGE_PUT (§53). */
+    putKeyPackage(resource: ResourceId, bytes: Uint8Array): Promise<IdentityAnswer>;
+    /** DATA_GET of the ranges (§49); throws IdentityRefused on a NACK. */
+    dataUnits(resource: ResourceId, ranges: readonly DataRange[]): Promise<readonly Uint8Array[]>;
+    /** DATA_PUT of one unit (§50). */
+    putDataUnit(resource: ResourceId, bytes: Uint8Array): Promise<IdentityAnswer>;
+    close(): void;
+}
+export interface IdentityNetwork {
+    /** An authenticated session as `signer` to the coordinator at `url`; throws IdentityUnavailable. */
+    connect(signer: Signer, url: string): Promise<IdentityChannel>;
+}
+/** The coordinator could not be reached or the session ended: a timeout is never a decision (§6). */
+export declare class IdentityUnavailable extends Error {
+    constructor(message: string);
+}
+/** A read the coordinator refused (NACK), e.g. AUTHORIZATION_FAILED for a revoked device (§8.6). */
+export declare class IdentityRefused extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** The READY extension of servers that support device records (W §37). */
+export declare const IDENTITY_EXTENSION = "identity-01";
+/** Connections reused within one flow run, by (Principal, URL); closed together. */
+export declare class ChannelPool {
+    #private;
+    constructor(network: IdentityNetwork);
+    get(signer: Signer, url: string): Promise<IdentityChannel>;
+    closeAll(): void;
+}
+export interface ConnectionNetworkOptions {
+    readonly now: () => number;
+    readonly webSocket?: WebSocketFactory;
+    /**
+     * A fresh timer per awaited reply (e.g. `() => sleep(30_000)` from the
+     * host): when it resolves first the request is "unavailable", never a
+     * decision (§6). Without it a request waits until the connection closes.
+     */
+    readonly timeout?: () => Promise<unknown>;
+}
+/** The identity network over LfcpConnection: one session per (Principal, coordinator). */
+export declare function connectionNetwork(options: ConnectionNetworkOptions): IdentityNetwork;
+//# sourceMappingURL=network.d.ts.map

package/dist/identity/network.js

@@ -0,0 +1,243 @@
+import { controlRecordId, toHex, } from "@openlfcp/core";
+import { createMessage, ERROR_CODE, } from "@openlfcp/wire";
+import { LfcpConnection } from "../connection.js";
+/** The coordinator could not be reached or the session ended: a timeout is never a decision (§6). */
+export class IdentityUnavailable extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IdentityUnavailable";
+    }
+}
+/** A read the coordinator refused (NACK), e.g. AUTHORIZATION_FAILED for a revoked device (§8.6). */
+export class IdentityRefused extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "IdentityRefused";
+    }
+}
+/** The READY extension of servers that support device records (W §37). */
+export const IDENTITY_EXTENSION = "identity-01";
+/** Connections reused within one flow run, by (Principal, URL); closed together. */
+export class ChannelPool {
+    #network;
+    #open = new Map();
+    constructor(network) {
+        this.#network = network;
+    }
+    get(signer, url) {
+        const key = `${toHex(signer.descriptor.principalId)} ${url}`;
+        let c = this.#open.get(key);
+        if (c === undefined) {
+            c = this.#network.connect(signer, url);
+            // A failed connection is not reused.
+            c.catch(() => this.#open.delete(key));
+            this.#open.set(key, c);
+        }
+        return c;
+    }
+    closeAll() {
+        for (const c of this.#open.values())
+            c.then((ch) => ch.close()).catch(() => undefined);
+        this.#open.clear();
+    }
+}
+const CODE_NAME = new Map(Object.entries(ERROR_CODE).map(([k, v]) => [v, k]));
+const codeName = (code) => CODE_NAME.get(code) ?? `ERROR_${code}`;
+const MAX_EPOCHS_PER_GET = 256;
+/** Request/response over one LfcpConnection. */
+class RequestSession {
+    #connection;
+    #inbox = [];
+    #waiters = [];
+    #closed = null;
+    #extensions = null;
+    #timeout;
+    constructor(options) {
+        this.#timeout = options.timeout;
+        this.#connection = new LfcpConnection({
+            url: options.url,
+            signer: options.signer,
+            now: options.now,
+            ...(options.webSocket === undefined ? {} : { webSocket: options.webSocket }),
+        }, {
+            state: () => undefined,
+            ready: (r) => {
+                this.#extensions = Object.freeze([...r.extensions]);
+                this.#wake();
+            },
+            message: (m) => {
+                this.#inbox.push(m);
+                this.#wake();
+            },
+            closed: (reason) => {
+                this.#closed = reason;
+                this.#wake();
+            },
+        });
+    }
+    get extensions() {
+        return this.#extensions ?? [];
+    }
+    #wake() {
+        const waiting = this.#waiters;
+        this.#waiters = [];
+        for (const w of waiting)
+            w();
+    }
+    async #until(take, what) {
+        let timedOut = false;
+        this.#timeout?.().then(() => {
+            timedOut = true;
+            this.#wake();
+        }, () => undefined);
+        for (;;) {
+            const v = take();
+            if (v !== undefined)
+                return v;
+            if (this.#closed !== null)
+                throw new IdentityUnavailable(`the connection closed while waiting for ${what}: ${this.#closed}`);
+            if (timedOut)
+                throw new IdentityUnavailable(`timed out waiting for ${what}`);
+            await new Promise((resolve) => this.#waiters.push(resolve));
+        }
+    }
+    async connect() {
+        this.#connection.connect();
+        await this.#until(() => (this.#extensions !== null ? true : undefined), "READY");
+    }
+    /** Sends a request and returns its correlated replies, until `done` says the last one arrived. */
+    async #request(m, what, done = () => true) {
+        this.#connection.send(m);
+        const id = toHex(m.messageId);
+        const replies = [];
+        for (;;) {
+            const reply = await this.#until(() => {
+                const i = this.#inbox.findIndex((r) => r.correlationId !== undefined && toHex(r.correlationId) === id);
+                return i === -1 ? undefined : this.#inbox.splice(i, 1)[0];
+            }, what);
+            replies.push(reply);
+            if (reply.type === "NACK" || done(reply))
+                return replies;
+        }
+    }
+    #answer(reply) {
+        if (reply?.type === "ACK" || reply?.type === "RESOURCE_HOSTED")
+            return { kind: "ack" };
+        if (reply?.type === "NACK") {
+            const head = reply.body.details;
+            return Object.freeze({
+                kind: "nack",
+                code: codeName(reply.body.code),
+                ...(head instanceof Uint8Array && head.length === 32
+                    ? { head: controlRecordId(head) }
+                    : {}),
+            });
+        }
+        throw new IdentityUnavailable(`unexpected answer ${reply?.type ?? "none"}`);
+    }
+    #refuse(reply, what) {
+        if (reply.type === "NACK")
+            throw new IdentityRefused(codeName(reply.body.code), `${what} was refused`);
+        throw new IdentityUnavailable(`${what} was answered with ${reply.type}`);
+    }
+    async host(genesis) {
+        const [reply] = await this.#request(createMessage("RESOURCE_HOST", { genesis }), "RESOURCE_HOSTED");
+        return this.#answer(reply);
+    }
+    async open(resource) {
+        const [reply] = await this.#request(createMessage("RESOURCE_OPEN", { resourceId: resource, heads: [], haves: [] }), "RESOURCE_OPENED");
+        if (reply?.type === "RESOURCE_OPENED")
+            return Object.freeze({ kind: "opened", heads: reply.body.heads, haves: reply.body.haves });
+        if (reply?.type === "NACK")
+            return { kind: "nack", code: codeName(reply.body.code) };
+        throw new IdentityUnavailable(`RESOURCE_OPEN was answered with ${reply?.type}`);
+    }
+    async control(resource, start) {
+        const opened = await this.open(resource);
+        if (opened.kind === "nack")
+            throw new IdentityRefused(opened.code, "RESOURCE_OPEN was refused");
+        const end = opened.heads.reduce((m, h) => (h.seq > m ? h.seq : m), -1n);
+        if (end < start)
+            return [];
+        const out = [];
+        const replies = await this.#request(createMessage("CONTROL_GET", { resourceId: resource, start, end }), "CONTROL_BATCH", (r) => {
+            if (r.type === "CONTROL_BATCH")
+                out.push(...r.body.objects);
+            return out.length >= Number(end - start + 1n);
+        });
+        const last = replies.at(-1);
+        if (last.type === "NACK")
+            this.#refuse(last, "CONTROL_GET");
+        return out;
+    }
+    async putControl(resource, expectedHead, record) {
+        const [reply] = await this.#request(createMessage("CONTROL_PUT", { resourceId: resource, expectedHead, record }), "the CONTROL_PUT answer");
+        return this.#answer(reply);
+    }
+    async keyPackages(resource, recipient, epochs) {
+        const out = [];
+        for (let i = 0; i < epochs.length; i += MAX_EPOCHS_PER_GET) {
+            const [reply] = await this.#request(createMessage("KEY_PACKAGE_GET", {
+                resourceId: resource,
+                recipient,
+                epochs: epochs.slice(i, i + MAX_EPOCHS_PER_GET),
+            }), "KEY_PACKAGE_BATCH");
+            if (reply?.type !== "KEY_PACKAGE_BATCH")
+                this.#refuse(reply, "KEY_PACKAGE_GET");
+            out.push(...reply.body.objects);
+        }
+        return out;
+    }
+    async putKeyPackage(resource, bytes) {
+        const [reply] = await this.#request(createMessage("KEY_PACKAGE_PUT", { resourceId: resource, objects: [bytes] }), "the KEY_PACKAGE_PUT answer");
+        return this.#answer(reply);
+    }
+    async dataUnits(resource, ranges) {
+        if (ranges.length === 0)
+            return [];
+        const want = ranges.reduce((n, r) => n + Number(r.end - r.start + 1n), 0);
+        const out = [];
+        const replies = await this.#request(createMessage("DATA_GET", { resourceId: resource, ranges }), "DATA_BATCH", (r) => {
+            if (r.type === "DATA_BATCH")
+                out.push(...r.body.objects);
+            // A server may hold fewer units than asked; an empty batch ends the answer.
+            return out.length >= want || (r.type === "DATA_BATCH" && r.body.objects.length === 0);
+        });
+        const last = replies.at(-1);
+        if (last.type === "NACK")
+            this.#refuse(last, "DATA_GET");
+        return out;
+    }
+    async putDataUnit(resource, bytes) {
+        const [reply] = await this.#request(createMessage("DATA_PUT", { resourceId: resource, objects: [bytes] }), "the DATA_PUT answer");
+        return this.#answer(reply);
+    }
+    close() {
+        this.#connection.close("the identity flow finished");
+    }
+}
+/** The identity network over LfcpConnection: one session per (Principal, coordinator). */
+export function connectionNetwork(options) {
+    return {
+        async connect(signer, url) {
+            const s = new RequestSession({
+                url,
+                signer,
+                now: options.now,
+                ...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+                ...(options.webSocket === undefined ? {} : { webSocket: options.webSocket }),
+            });
+            try {
+                await s.connect();
+            }
+            catch (e) {
+                s.close();
+                throw e;
+            }
+            return s;
+        },
+    };
+}
+//# sourceMappingURL=network.js.map

package/dist/identity/pairing-request.d.ts

@@ -0,0 +1,147 @@
+import { type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type CertificateChain, type DeviceCertificatePayload } from "@openlfcp/wire";
+import type { FlowOptions } from "./devices.js";
+import type { PairingLinkText } from "./pairing.js";
+import type { LinearChain } from "./phases.js";
+import { type IdentityDocumentFactory } from "./resource.js";
+/**
+ * Pairing a new installation, the new side `B` (IDENTITY-PROFILE-01 §5.3
+ * steps 2, 3, 8 and 11; §6). `B` opens the Identity Resource as the
+ * pairing device `J` of the link, verifies it, persists its candidates and
+ * writes its request as `J`; later it learns its result from the chain
+ * alone: while `J` is active the request waits; once `J` is revoked the
+ * revoked-reader prefix (W §41) says whether the session was consumed
+ * (reason 3, with the approval digest `d`) or cancelled. The first
+ * verified certificate naming `D_B` whose payload digest is `d` decides;
+ * a timeout never does.
+ */
+export interface RequestPairingOptions extends FlowOptions {
+    readonly link: string | PairingLinkText;
+    readonly label: string;
+    /** 0 personal, 1 service. */
+    readonly kind: 0 | 1;
+    /** Service: the Resources its human chose from the roster. */
+    readonly scope?: readonly ResourceId[];
+    /**
+     * Service, headless (§5.3 "Headless installation"): the Resources its
+     * human chose, by roster name, resolved on the roster read as `J` once
+     * the link is verified, and added to `scope`. A name that matches no
+     * roster entry, or several, writes no request (`unknown-sections`).
+     */
+    readonly sections?: readonly string[];
+    readonly platform?: string;
+    /** RFC 3339 UTC for `requested_at`. */
+    readonly requestedAt?: string;
+    readonly document: IdentityDocumentFactory;
+}
+export type RequestPairingResult = {
+    readonly kind: "requested";
+    readonly operation: string;
+    readonly identity: ResourceId;
+    /** §5.2: show it; the human compares it with A's screen. */
+    readonly fingerprint: string;
+}
+/**
+ * The link is rejected (§5.2): it does not parse, or its secret is not its
+ * device's. Like `not-a-session`, a client-local outcome with no wire code
+ * (W §62; the corpora name it PAIRING_LINK_REJECTED): nothing more is sent
+ * as `J` and no request is written.
+ */
+ | {
+    readonly kind: "invalid-link";
+    readonly reason: string;
+}
+/** The link is rejected (§5.2): `I` is not an Identity Resource, or `J` is not an active pairing device of its owner. */
+ | {
+    readonly kind: "not-a-session";
+    readonly reason: string;
+}
+/**
+ * A requested section name matches no roster entry, or several (§5.3
+ * headless): nothing is persisted or written. `available` lists the
+ * names of the roster Resources the device may request.
+ */
+ | {
+    readonly kind: "unknown-sections";
+    readonly unknown: readonly string[];
+    readonly available: readonly string[];
+}
+/** No DEK of `I` or no root unit 1: the document cannot be verified (§5.3 step 2). */
+ | {
+    readonly kind: "missing-material";
+    readonly missing: readonly string[];
+}
+/** The coordinator refused the request unit (e.g. ACTOR_EQUIVOCATION: another installation used the link at once). */
+ | {
+    readonly kind: "refused";
+    readonly operation: string;
+    readonly code: string;
+} | {
+    readonly kind: "unavailable";
+    readonly operation?: string;
+    readonly reason: string;
+};
+/** §5.3 steps 2–3. */
+export declare function requestPairing(o: RequestPairingOptions): Promise<RequestPairingResult>;
+/** §6: the status of one Resource for the new device, from its own observations only. */
+export type CandidateStatus = "ready" | "waiting-for-keys" | "pending-registration" | "not-granted" | "unproven" | "unreachable" | "unsupported";
+export interface CandidateResult {
+    readonly resource: ResourceId;
+    readonly status: CandidateStatus;
+    /** The roster name persisted with the candidate (§5.3 step 3), for display; absent for I. */
+    readonly name?: string;
+}
+export type PairingOutcome = 
+/** `J` is still active: the request waits for the managing device (§5.3 step 3). */
+{
+    readonly kind: "waiting";
+}
+/** The session was cancelled (reason 0): final (§5.3 step 8). */
+ | {
+    readonly kind: "rejected";
+}
+/**
+ * The session was consumed. Without a certificate yet: "approved,
+ * waiting for registration"; with it, each candidate's status (§6).
+ */
+ | {
+    readonly kind: "approved";
+    readonly certificate: CertificateChain | null;
+    readonly candidates: readonly CandidateResult[];
+    /** Certificates naming D_B with another digest: reported, never used (§5.3 step 8). */
+    readonly foreignCertificates: number;
+}
+/** `J` is no longer readable and no revoked-reader proof is available yet. */
+ | {
+    readonly kind: "unknown";
+    readonly reason: string;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+/** What a candidate's own chain proves about the device's approved certificate (§5.3 step 8). */
+export interface CandidateEvidence {
+    /** The certificate IDs of every accepted leaf naming the device, oldest first. */
+    readonly leaves: readonly Hash32[];
+    /** A leaf whose payload digest is the approval was accepted here at some point. */
+    readonly proven: boolean;
+    /** Registered and active here, or still pending registration. */
+    readonly registration: "active" | "pending";
+    /**
+     * The device may use this Resource: proven, active, and its current leaf
+     * has the result's kind, mask and scope (N8). A Resource where the device
+     * is registered without proof is "approval not provable here".
+     */
+    readonly usable: boolean;
+}
+export declare function candidateEvidence(chain: LinearChain, device: PrincipalId, digest: Hash32, result: DeviceCertificatePayload): CandidateEvidence;
+/**
+ * §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 declare function completePairing(o: FlowOptions & {
+    readonly operation: string;
+    readonly document: IdentityDocumentFactory;
+}): Promise<PairingOutcome>;
+//# sourceMappingURL=pairing-request.d.ts.map