@openlfcp/client 0.2.2 → 0.3.1

package/dist/identity/devices.js

@@ -0,0 +1,221 @@
+import { bytesEqual, LfcpError, secureRandom, toHex, } from "@openlfcp/core";
+import { generateAgreementKeyPair, generateSigningKeyPair } from "@openlfcp/crypto";
+import { activeDevice, authorizeDeviceGrant, certificateChain, checkDeviceCertificatePayload, DEVICE_ABILITY, DEVICE_KIND, newDeviceCertificateSerial, ownerAction, principalDescriptorFromKeys, signControlRecord, signDeviceCertificate, validateControlChain, } from "@openlfcp/wire";
+import { deliverKeys, fetchDeks, IdentityConflict, runControlPhase, } from "./context.js";
+import { newOperationId, OperationJournal, PackageLedger } from "./journal.js";
+import { ChannelPool, IDENTITY_EXTENSION, IdentityRefused, IdentityUnavailable, } from "./network.js";
+import { classifyRegister } from "./phases.js";
+/** The mask presets of IDENTITY-PROFILE-01 §5.4 (decision I6). Codes 9 and 11 are never listed. */
+export const MASK_PRESETS = Object.freeze({
+    full: Object.freeze({
+        kind: DEVICE_KIND.PERSONAL,
+        mask: [1n, 2n, 3n, 4n, 5n, 6n, 7n, 8n, 10n, 12n, 13n],
+    }),
+    edit: Object.freeze({ kind: DEVICE_KIND.PERSONAL, mask: [1n, 2n, 3n] }),
+    read: Object.freeze({ kind: DEVICE_KIND.PERSONAL, mask: [1n] }),
+    service: Object.freeze({ kind: DEVICE_KIND.SERVICE, mask: [1n, 2n] }),
+});
+const hasCode = (mask, code) => mask.includes(code);
+/**
+ * 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 function issuerCertificates(state, issuer, root) {
+    if (bytesEqual(issuer, root))
+        return [];
+    const d = activeDevice(state, issuer);
+    if (d === undefined || d.chain === null || !bytesEqual(d.root, root))
+        return undefined;
+    return d.chain.certificates;
+}
+/** A leaf payload for `device` with a fresh serial (W §7.3). */
+export function leafPayload(root, device, kind, mask, scope) {
+    return Object.freeze({
+        root,
+        device,
+        kind,
+        mask: Object.freeze([...mask].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))),
+        scope: Object.freeze([...scope]),
+        serial: newDeviceCertificateSerial(),
+    });
+}
+/** An Ed25519/X25519 Principal used only to give a not-yet-signed leaf a certificate shape. */
+function placeholderSigner() {
+    const key = generateSigningKeyPair();
+    return { key, descriptor: principalDescriptorFromKeys(key, generateAgreementKeyPair()) };
+}
+/**
+ * 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 function checkIssuance(options) {
+    const { chain, issuer, leaf } = options;
+    const root = leaf.root;
+    const no = (reason) => ({ feasible: false, reason });
+    const issuers = issuerCertificates(chain.state, issuer.descriptor.principalId, root);
+    if (issuers === undefined)
+        return no("the issuer is not the root or an active device of it");
+    let future;
+    try {
+        checkDeviceCertificatePayload(leaf);
+        future = certificateChain([signDeviceCertificate(leaf, placeholderSigner()), ...issuers], root);
+    }
+    catch (e) {
+        if (e instanceof LfcpError)
+            return no(e.message);
+        throw e;
+    }
+    let state = chain.state;
+    if (options.pairing !== undefined) {
+        const consume = signControlRecord({ resourceId: state.resourceId, controlSeq: state.seq + 1n, prevControlId: state.head }, {
+            type: "DEVICE_REVOKE",
+            root,
+            device: options.pairing,
+            reason: 3n,
+            approval: future.leaf.payloadDigest,
+        }, issuer);
+        const after = validateControlChain([
+            ...chain.records.map((r) => r.signed.bytes),
+            consume.bytes,
+        ]);
+        if (after.kind !== "linear")
+            return no(`the session cannot be consumed by this issuer (${after.kind === "invalid" ? after.error.message : after.kind})`);
+        state = after.state;
+    }
+    const a = authorizeDeviceGrant(state, issuer.descriptor.principalId, {
+        type: "DEVICE_GRANT",
+        root,
+        chain: future,
+        ...(options.pairing === undefined ? {} : { pairingDevice: options.pairing }),
+    });
+    return a.allowed ? { feasible: true } : no(a.reason);
+}
+/** Signs `leaf` through `issuer` and returns the complete chain (§5.3 step 6). */
+export function signChain(state, issuer, leaf) {
+    const issuers = issuerCertificates(state, issuer.descriptor.principalId, leaf.root);
+    if (issuers === undefined)
+        throw new LfcpError("AUTHORIZATION_FAILED", "the issuer is not the root or an active device of it");
+    return certificateChain([signDeviceCertificate(leaf, issuer), ...issuers], leaf.root);
+}
+/**
+ * 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 function mayManageDevices(state, actor, root) {
+    if (bytesEqual(actor, root))
+        return true;
+    const d = activeDevice(state, actor);
+    if (d === undefined || !bytesEqual(d.root, root))
+        return false;
+    if (hasCode(d.mask, DEVICE_ABILITY.DEVICE_MANAGE))
+        return true;
+    return bytesEqual(state.owner.principalId, root) && ownerAction(state, actor);
+}
+/**
+ * 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 async function registerDevice(options) {
+    const journal = new OperationJournal(options.storage);
+    const ledger = new PackageLedger(options.storage);
+    const device = options.chain.leaf.payload.device;
+    const root = options.chain.root;
+    const operation = options.operation ?? newOperationId("register-device", secureRandom(8));
+    if ((await journal.get(operation)) === undefined)
+        await journal.begin({
+            id: operation,
+            kind: "register-device",
+            createdAt: options.now(),
+            intent: {
+                device: toHex(device.principalId),
+                root: toHex(root),
+                leaf: toHex(options.chain.leaf.id),
+                targets: options.targets.map((t) => ({ resource: toHex(t.resource), url: t.url })),
+            },
+        });
+    const pool = new ChannelPool(options.network);
+    const results = [];
+    const me = options.installation.signer;
+    try {
+        for (const t of options.targets) {
+            const result = (status, extra = {}) => results.push(Object.freeze({ resource: t.resource, status, ...extra }));
+            try {
+                const channel = await pool.get(me, t.url);
+                if (!channel.extensions.includes(IDENTITY_EXTENSION)) {
+                    result("unsupported");
+                    continue;
+                }
+                const outcome = await runControlPhase(options.storage, channel, journal, operation, {
+                    id: `register:${toHex(t.resource)}`,
+                    kind: "register",
+                    resource: t.resource,
+                    classify: (chain, isOwn) => {
+                        const s = classifyRegister(chain, { root, chain: options.chain, isOwnRecord: isOwn });
+                        if (s === "pending" && !mayManageDevices(chain.state, me.descriptor.principalId, root))
+                            throw new NotAuthorizedHere();
+                        return s;
+                    },
+                    build: (chain) => signControlRecord({
+                        resourceId: t.resource,
+                        controlSeq: chain.state.seq + 1n,
+                        prevControlId: chain.state.head,
+                    }, { type: "DEVICE_GRANT", root, chain: options.chain }, me).bytes,
+                });
+                if (outcome.state === "superseded") {
+                    result("superseded");
+                    continue;
+                }
+                if (outcome.state === "refused") {
+                    result("refused", { code: outcome.code ?? "refused" });
+                    continue;
+                }
+                const deks = await fetchDeks(options.storage, options.secrets, channel, outcome.chain, options.installation);
+                const keys = await deliverKeys({
+                    channel,
+                    ledger,
+                    chain: outcome.chain,
+                    sender: me,
+                    recipients: [device],
+                    deks,
+                });
+                result("registered", { keys });
+            }
+            catch (e) {
+                if (e instanceof NotAuthorizedHere)
+                    result("not-authorized");
+                else if (e instanceof IdentityUnavailable)
+                    result("unreachable");
+                else if (e instanceof IdentityRefused)
+                    result("not-authorized", { code: e.code });
+                else if (e instanceof IdentityConflict)
+                    result("conflict");
+                else
+                    throw e;
+            }
+        }
+    }
+    finally {
+        pool.closeAll();
+    }
+    const open = results.some((r) => r.status === "unreachable" || r.status === "conflict");
+    await journal.setStatus(operation, open ? "open" : "done");
+    return Object.freeze({ operation, results: Object.freeze(results) });
+}
+class NotAuthorizedHere extends Error {
+}
+//# sourceMappingURL=devices.js.map

package/dist/identity/document.d.ts

@@ -0,0 +1,112 @@
+import { type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type ControlState, type DataProfileCodec } from "@openlfcp/wire";
+/**
+ * The Identity Resource's document, as the identity flows see it
+ * (IDENTITY-PROFILE-01 §§2–4).
+ *
+ * @openlfcp/client never binds to the CRDT engine (LFCP-031): the
+ * application passes an IdentityDocumentPort, normally backed by
+ * @openlfcp/shared-objects' IdentityReplica, which owns admission (§3) and
+ * state validation (§4). The flows only produce intents, carry the
+ * resulting plaintext in Data Units and read the validated entries back.
+ * Nothing in the document confers authority (§4 rule 5): every decision
+ * of a flow is taken from a Control Chain.
+ */
+/** IDENTITY-PROFILE-01's Data Profile identifier. */
+export declare const IDENTITY_PROFILE = "org.openlfcp.identity.v1";
+/** §2.3: the writer's class at the Data Unit's control_ref. */
+export type IdentityWriterClass = "root" | "personal" | "pairing" | "other";
+export interface IdentityAuthor {
+    readonly signer: PrincipalId;
+    /** The LFCP Data Unit actor sequence of the unit that carries the change. */
+    readonly actorSeq: bigint;
+    readonly writerClass: IdentityWriterClass;
+}
+export interface RosterEntryValue {
+    readonly profile: string;
+    readonly endpoints: readonly string[];
+    readonly coordinator: string;
+    readonly name?: string;
+    readonly archived?: boolean;
+}
+export interface DeviceEntryValue {
+    readonly label: string;
+    readonly kind: 0 | 1;
+    readonly platform?: string;
+    readonly added_at?: string;
+    readonly revoked?: boolean;
+    readonly missing_keys?: Readonly<Record<string, readonly (bigint | number)[]>>;
+}
+export interface PairingRequestValue {
+    /** base64url of the deterministic CBOR principal descriptor (W §7). */
+    readonly descriptor: string;
+    /** PrincipalRef of the pairing device that wrote the request. */
+    readonly pairing: string;
+    readonly label: string;
+    readonly kind: 0 | 1;
+    readonly scope?: readonly string[];
+    readonly platform?: string;
+    readonly requested_at?: string;
+}
+export type IdentityIntent = {
+    readonly intent: "identity.initialize";
+} | {
+    readonly intent: "roster.put";
+    readonly key: string;
+    readonly entry: RosterEntryValue;
+} | {
+    readonly intent: "device.put";
+    readonly key: string;
+    readonly entry: DeviceEntryValue;
+} | {
+    readonly intent: "request.put";
+    readonly key: string;
+    readonly entry: PairingRequestValue;
+} | {
+    readonly intent: "roster.delete" | "device.delete" | "request.delete";
+    readonly key: string;
+};
+export interface IdentityDocumentPort {
+    /**
+     * The plaintext of one new change by `author` carrying `intents` in one
+     * transaction, already applied to the local document. Throws when the
+     * document refuses it (the actor sequence is then not used).
+     */
+    write(author: IdentityAuthor, intents: readonly IdentityIntent[]): Uint8Array;
+    /** Applies a received unit's plaintext (§3 admission); false when it is refused or held. */
+    receive(plaintext: Uint8Array, author: IdentityAuthor): boolean;
+    /** Whether the initial change (§2.2) is admitted. */
+    initialized(): boolean;
+    /** The valid roster entries (§4 rule 1), by ResourceRef. */
+    roster(): ReadonlyMap<string, RosterEntryValue>;
+    /** The valid device entries, by PrincipalRef. */
+    devices(): ReadonlyMap<string, DeviceEntryValue>;
+    /** The valid pairing requests, by PrincipalRef. */
+    requests(): ReadonlyMap<string, PairingRequestValue>;
+    /**
+     * The admitted changes that created, wrote into or deleted `table[key]`,
+     * in causal order, with the signer of each (IdentityReplica.origins).
+     * Taken from the changes themselves, never inferred from the merged
+     * state: §5.3 step 4 accepts a request only when every change that
+     * wrote it was signed by the session's pairing device, and the approval
+     * journals these change hashes.
+     */
+    origins(table: "roster" | "devices" | "requests", key: string): readonly {
+        readonly hash: string;
+        readonly signer: PrincipalId;
+    }[];
+}
+/** A passthrough Data Unit codec: the port produces and consumes the plaintext. */
+export declare const identityPlaintextCodec: DataProfileCodec<Uint8Array>;
+/** ResourceRef (§2.1): unpadded base64url of the 32-byte Resource ID. */
+export declare const resourceRef: (id: ResourceId) => string;
+/** PrincipalRef (SOP §27): "p:" + unpadded base64url of the Principal ID. */
+export declare const principalRefOf: (id: PrincipalId) => string;
+/** The Principal ID of a PrincipalRef; undefined when it is malformed. */
+export declare function principalOfRef(ref: string): PrincipalId | undefined;
+/**
+ * §2.3: the writer class of `signer` from the Identity Resource's Control
+ * state at the unit's control_ref; `root` is the Genesis owner.
+ */
+export declare function identityWriterClass(state: ControlState, root: PrincipalId, signer: PrincipalId): IdentityWriterClass;
+//# sourceMappingURL=document.d.ts.map

package/dist/identity/document.js

@@ -0,0 +1,54 @@
+import { bytesEqual, fromBase64url, principalId, toBase64url, toHex, } from "@openlfcp/core";
+import { DEVICE_KIND } from "@openlfcp/wire";
+/**
+ * The Identity Resource's document, as the identity flows see it
+ * (IDENTITY-PROFILE-01 §§2–4).
+ *
+ * @openlfcp/client never binds to the CRDT engine (LFCP-031): the
+ * application passes an IdentityDocumentPort, normally backed by
+ * @openlfcp/shared-objects' IdentityReplica, which owns admission (§3) and
+ * state validation (§4). The flows only produce intents, carry the
+ * resulting plaintext in Data Units and read the validated entries back.
+ * Nothing in the document confers authority (§4 rule 5): every decision
+ * of a flow is taken from a Control Chain.
+ */
+/** IDENTITY-PROFILE-01's Data Profile identifier. */
+export const IDENTITY_PROFILE = "org.openlfcp.identity.v1";
+/** A passthrough Data Unit codec: the port produces and consumes the plaintext. */
+export const identityPlaintextCodec = Object.freeze({
+    dataProfile: IDENTITY_PROFILE,
+    encode: (plaintext) => plaintext,
+    decode: (plaintext) => plaintext,
+});
+/** ResourceRef (§2.1): unpadded base64url of the 32-byte Resource ID. */
+export const resourceRef = (id) => toBase64url(id);
+/** PrincipalRef (SOP §27): "p:" + unpadded base64url of the Principal ID. */
+export const principalRefOf = (id) => `p:${toBase64url(id)}`;
+/** The Principal ID of a PrincipalRef; undefined when it is malformed. */
+export function principalOfRef(ref) {
+    if (!ref.startsWith("p:") || ref.length !== 45)
+        return undefined;
+    try {
+        return principalId(fromBase64url(ref.slice(2)));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * §2.3: the writer class of `signer` from the Identity Resource's Control
+ * state at the unit's control_ref; `root` is the Genesis owner.
+ */
+export function identityWriterClass(state, root, signer) {
+    if (bytesEqual(signer, root))
+        return "root";
+    const d = state.devices.get(toHex(signer));
+    if (d === undefined || !bytesEqual(d.root, root))
+        return "other";
+    if (d.kind === DEVICE_KIND.PERSONAL)
+        return "personal";
+    if (d.kind === DEVICE_KIND.PAIRING)
+        return "pairing";
+    return "other";
+}
+//# sourceMappingURL=document.js.map

package/dist/identity/index.d.ts

@@ -0,0 +1,17 @@
+/** Identity flows (IDENTITY-PROFILE-01 §§5–9, LFCP-04-410). */
+export { acceptInvitationAsDevice, claimForRootRecord, createResourceAsDevice, type DeviceAcceptResult, type DeviceCreateResult, type DeviceResourceResult, type IncompleteDeviceResource, selfRegistrationRecord, } from "./accept.js";
+export { type DocumentWrite, deliverKeys, extendChain, fetchDeks, genesisOwner, heldDeks, IdentityConflict, type IdentityDocumentLoad, type IdentityStorage, type Installation, type KeyDelivery, loadIdentityDocument, type PhaseOutcome, readersAt, runControlPhase, runUnitPhase, sealIdentityUnit, storeDek, syncChain, } from "./context.js";
+export { checkIssuance, type Feasibility, type FlowOptions, issuerCertificates, leafPayload, MASK_PRESETS, type MaskPreset, mayManageDevices, type RegisterTarget, type RegistrationResult, type RegistrationStatus, registerDevice, signChain, } from "./devices.js";
+export { type DeviceEntryValue, IDENTITY_PROFILE, type IdentityAuthor, type IdentityDocumentPort, type IdentityIntent, type IdentityWriterClass, identityPlaintextCodec, identityWriterClass, type PairingRequestValue, principalOfRef, principalRefOf, type RosterEntryValue, resourceRef, } from "./document.js";
+export { type JournalOperation, type JournalPhase, type LedgerEntry, OperationJournal, type OperationKind, type OperationStatus, PackageLedger, pairingSecretRef, pendingDekRef, } from "./journal.js";
+export { ChannelPool, type ConnectionNetworkOptions, connectionNetwork, IDENTITY_EXTENSION, type IdentityAnswer, type IdentityChannel, type IdentityNetwork, IdentityRefused, IdentityUnavailable, type OpenAnswer, } from "./network.js";
+export { type ApprovalResult, approvedGrantRecord, approvePairing, type CancelResult, cancelPairing, cancelRecord, consumeRecord, createPairingSession, openPairingSessions, PairingLinkText, type PairingReview, type PairingSessionResult, pairingRequests, resumeApproval, resumePairingSession, } from "./pairing.js";
+export { type CandidateEvidence, type CandidateResult, type CandidateStatus, candidateEvidence, completePairing, type PairingOutcome, type RequestPairingOptions, type RequestPairingResult, requestPairing, } from "./pairing-request.js";
+export { certificateInScope, classifyCancel, classifyConsume, classifyPackage, classifyRegister, classifyRevoke, classifyRotate, keyEpochAfter, type LinearChain, type PhaseState, type RegisterPhase, recordSeq, } from "./phases.js";
+export { type RevocationStatus, revocationStatus } from "./proof.js";
+export { planReconciliation, type ReconcileStep, reconcileDevices, reconcileRecord, type TargetReconciliation, } from "./reconcile.js";
+export { type CreatedIdentityResource, type CreateIdentityResourceOptions, createIdentityResource, type IdentityDocumentFactory, type IdentityFlowOptions, identityTarget, localIdentityResource, resumeIdentityCreation, setLocalIdentityResource, } from "./resource.js";
+export { previewRevocation, type ResourcePreview, type RevocationPreview, type RevocationResult, type RevokeDeviceResult, revokeDevice, rotateIfExposed, } from "./revocation.js";
+export { type AddToRosterOptions, type AddToRosterResult, addToRoster, type RosterWrite, writeRosterEntry, } from "./roster.js";
+export { type ExposingRevocation, exposingRevocationsSince, type FrontierData, type LocalAccepted, type RotationOutcome, type RotationStatus, type RotatorTest, rotateAfter, rotatorTest, verifiedFrontier, } from "./rotation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/identity/index.js

@@ -0,0 +1,17 @@
+/** Identity flows (IDENTITY-PROFILE-01 §§5–9, LFCP-04-410). */
+export { acceptInvitationAsDevice, claimForRootRecord, createResourceAsDevice, selfRegistrationRecord, } from "./accept.js";
+export { deliverKeys, extendChain, fetchDeks, genesisOwner, heldDeks, IdentityConflict, loadIdentityDocument, readersAt, runControlPhase, runUnitPhase, sealIdentityUnit, storeDek, syncChain, } from "./context.js";
+export { checkIssuance, issuerCertificates, leafPayload, MASK_PRESETS, mayManageDevices, registerDevice, signChain, } from "./devices.js";
+export { IDENTITY_PROFILE, identityPlaintextCodec, identityWriterClass, principalOfRef, principalRefOf, resourceRef, } from "./document.js";
+export { OperationJournal, PackageLedger, pairingSecretRef, pendingDekRef, } from "./journal.js";
+export { ChannelPool, connectionNetwork, IDENTITY_EXTENSION, IdentityRefused, IdentityUnavailable, } from "./network.js";
+export { approvedGrantRecord, approvePairing, cancelPairing, cancelRecord, consumeRecord, createPairingSession, openPairingSessions, PairingLinkText, pairingRequests, resumeApproval, resumePairingSession, } from "./pairing.js";
+export { candidateEvidence, completePairing, requestPairing, } from "./pairing-request.js";
+export { certificateInScope, classifyCancel, classifyConsume, classifyPackage, classifyRegister, classifyRevoke, classifyRotate, keyEpochAfter, recordSeq, } from "./phases.js";
+export { revocationStatus } from "./proof.js";
+export { planReconciliation, reconcileDevices, reconcileRecord, } from "./reconcile.js";
+export { createIdentityResource, identityTarget, localIdentityResource, resumeIdentityCreation, setLocalIdentityResource, } from "./resource.js";
+export { previewRevocation, revokeDevice, rotateIfExposed, } from "./revocation.js";
+export { addToRoster, writeRosterEntry, } from "./roster.js";
+export { exposingRevocationsSince, rotateAfter, rotatorTest, verifiedFrontier, } from "./rotation.js";
+//# sourceMappingURL=index.js.map

package/dist/identity/journal.d.ts

@@ -0,0 +1,139 @@
+import { type DataEpoch, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type ResourceDEK } from "@openlfcp/crypto";
+import { type LfcpStorage, type SecretStore } from "@openlfcp/storage";
+import type { PhaseState } from "./phases.js";
+/**
+ * The durable operation journal and the package ledger
+ * (IDENTITY-PROFILE-01 §9.1, §9.5, §9.8).
+ *
+ * Pairing, accepting an invitation, creating a Resource, revocation with
+ * rotation and reconciliation each commit several records and packages,
+ * possibly on several Resources. Before any record or package is sent the
+ * client persists the operation's intent and the exact signed bytes of the
+ * next record; after each ACK it persists the committed record ID. A phase
+ * is repeated only by re-sending the same exact bytes; after a
+ * CONTROL_HEAD_MISMATCH or a restart it is classified against the accepted
+ * chain (phases.ts) and rebuilt only when it is still `pending` on a new
+ * head.
+ *
+ * Journal rows are local marks (`identity-op:<id>`) and hold no secrets
+ * (§9.8): a bearer link, a pairing device's keys and a DEK go to the
+ * SecretStore only, under the references below, before the row that names
+ * them is written (LFCP-034 ordering).
+ */
+export type OperationKind = "create-identity" | "pairing-session" | "pairing-approval" | "pairing-request" | "register-device" | "revoke-device" | "rotate" | "reconcile" | "accept-invitation" | "create-resource" | "add-to-roster";
+/** The state of a whole operation. */
+export type OperationStatus = 
+/** Phases remain; resume it. */
+"open"
+/** Every phase is committed or complete. */
+ | "done"
+/** A phase was superseded: the operation ended without its effect (§9.2). */
+ | "superseded"
+/** The human or the flow abandoned it (a cancelled session, a refused request). */
+ | "abandoned";
+/** A journaled phase. Byte strings are hex; every value is public. */
+export interface JournalPhase {
+    /** Unique within the operation, e.g. `consume`, `register:<resource hex>`. */
+    readonly id: string;
+    readonly kind: "host" | "unit" | "consume" | "register" | "cancel" | "revoke" | "rotate" | "claim" | "document";
+    /** The Resource the phase acts on (hex). */
+    readonly resource: string;
+    readonly state: PhaseState | "refused";
+    /** The exact signed bytes of the record or unit to (re)send, persisted before sending. */
+    readonly bytes?: string;
+    /** The head those bytes were built on (their prev_control_id), for a Control Record. */
+    readonly expectedHead?: string;
+    /** Every record ID this installation built for the phase, in order (§9.2 committed-own). */
+    readonly sent?: readonly string[];
+    /** The committed record ID, after the ACK (or after classification found it). */
+    readonly recordId?: string;
+    /** The NACK code of a refused phase. */
+    readonly code?: string;
+    /** Phase-specific public facts (a digest, a revocation sequence, an epoch). */
+    readonly facts?: Readonly<Record<string, string>>;
+}
+export interface JournalOperation {
+    readonly v: 1;
+    readonly id: string;
+    readonly kind: OperationKind;
+    readonly status: OperationStatus;
+    /** Milliseconds since the epoch, from the caller's clock; display only. */
+    readonly createdAt: number;
+    /** The operation's intent: public facts only (§9.8). */
+    readonly intent: Readonly<Record<string, unknown>>;
+    readonly phases: readonly JournalPhase[];
+}
+type JournalStorage = Pick<LfcpStorage, "localMarks" | "commit">;
+/** The durable operation journal (§9.1). */
+export declare class OperationJournal {
+    #private;
+    constructor(storage: JournalStorage);
+    /** Persists a new operation before any of its records is sent. */
+    begin(op: Omit<JournalOperation, "v" | "status" | "phases"> & {
+        readonly phases?: readonly JournalPhase[];
+    }): Promise<JournalOperation>;
+    get(id: string): Promise<JournalOperation | undefined>;
+    /** Every journaled operation, optionally of one kind and status, oldest first. */
+    list(filter?: {
+        readonly kind?: OperationKind;
+        readonly status?: OperationStatus;
+    }): Promise<readonly JournalOperation[]>;
+    /** Writes the phase (replacing the one with its ID), durably. */
+    putPhase(id: string, phase: JournalPhase): Promise<JournalOperation>;
+    /** Updates the intent with more public facts (e.g. the session's record IDs). */
+    updateIntent(id: string, patch: Readonly<Record<string, unknown>>): Promise<JournalOperation>;
+    setStatus(id: string, status: OperationStatus): Promise<JournalOperation>;
+    /** Removes a finished operation's row. */
+    remove(id: string): Promise<void>;
+    load(id: string): Promise<JournalOperation>;
+}
+/** The phase `id` of `op`, if journaled. */
+export declare const phaseOf: (op: JournalOperation, id: string) => JournalPhase | undefined;
+/** One sent Key Package (§9.5). */
+export interface LedgerEntry {
+    readonly resource: ResourceId;
+    readonly epoch: DataEpoch;
+    readonly recipient: PrincipalId;
+    readonly packageId: Hash32;
+}
+/**
+ * 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 declare class PackageLedger {
+    #private;
+    constructor(storage: JournalStorage);
+    /** Records an acknowledged package and drops its pending bytes, in one commit. */
+    record(entry: LedgerEntry): Promise<void>;
+    /** The exact bytes of a package sent but not yet acknowledged (§9.1). */
+    pending(resource: ResourceId, epoch: DataEpoch, recipient: PrincipalId): Promise<Uint8Array | undefined>;
+    /** Persists a package's exact bytes before it is sent. */
+    putPending(resource: ResourceId, epoch: DataEpoch, recipient: PrincipalId, bytes: Uint8Array): Promise<void>;
+    has(resource: ResourceId, epoch: DataEpoch, recipient: PrincipalId): Promise<boolean>;
+    /** Every entry for `resource`. */
+    list(resource: ResourceId): Promise<readonly LedgerEntry[]>;
+    /**
+     * "Re-send keys" (§7.1 step 3): forgets every package sent to
+     * `recipient`, in `resource` or everywhere, so the next reconciliation
+     * re-seals them.
+     */
+    clear(recipient: PrincipalId, resource?: ResourceId): Promise<number>;
+}
+/**
+ * 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 declare const pendingDekRef: (resource: ResourceId, operation: string) => import("@openlfcp/storage").SecretRef;
+/** The SecretStore slot of a pairing device's invite-secret (§5.2, §9.8). */
+export declare const pairingSecretRef: (pairingDevice: PrincipalId) => import("@openlfcp/storage").SecretRef;
+export declare function putPendingDek(secrets: SecretStore, resource: ResourceId, operation: string, dek: ResourceDEK): Promise<void>;
+export declare function getPendingDek(secrets: SecretStore, resource: ResourceId, operation: string): Promise<ResourceDEK | undefined>;
+/** A fresh, unique operation ID. */
+export declare function newOperationId(kind: OperationKind, random: Uint8Array): string;
+export {};
+//# sourceMappingURL=journal.d.ts.map