@openlfcp/client 0.2.2 → 0.3.1

package/dist/identity/context.d.ts

@@ -0,0 +1,214 @@
+import { type ControlRecordId, type DataEpoch, type DataUnitId, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type AgreementKeyPair, type ResourceDEK } from "@openlfcp/crypto";
+import { type LfcpStorage, type SecretStore } from "@openlfcp/storage";
+import { type DataUnitPayload, type Parsed, type PrincipalDescriptor, type Signer } from "@openlfcp/wire";
+import { type IdentityDocumentPort, type IdentityIntent } from "./document.js";
+import { type JournalPhase, type OperationJournal, type PackageLedger } from "./journal.js";
+import type { IdentityChannel } from "./network.js";
+import type { LinearChain, PhaseState } from "./phases.js";
+/** The storage the identity flows use. */
+export type IdentityStorage = Pick<LfcpStorage, "control" | "commit" | "localMarks" | "actorSequences">;
+/** This installation, as the identity flows act for it. */
+export interface Installation {
+    /** Its Principal's signer: a device's, or the root's when it has no devices yet. */
+    readonly signer: Signer;
+    /** Its X25519 key, to open Key Packages. */
+    readonly agreement: AgreementKeyPair;
+}
+/** The Resource or the Identity Resource is forked (§9.7): approval, reconciliation and rotation are suspended. */
+export declare class IdentityConflict extends Error {
+    readonly resource: ResourceId;
+    constructor(resource: ResourceId, message: string);
+}
+/**
+ * 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 declare function syncChain(storage: IdentityStorage, channel: IdentityChannel, resource: ResourceId): Promise<LinearChain>;
+/** Validates `chain` extended with `record` (e.g. after an ACK) and stores it. */
+export declare function extendChain(storage: IdentityStorage, chain: LinearChain, record: Uint8Array): Promise<LinearChain>;
+export interface ControlPhaseSpec {
+    readonly id: string;
+    readonly kind: JournalPhase["kind"];
+    readonly resource: ResourceId;
+    readonly facts?: Readonly<Record<string, string>>;
+    /** §9.2 classification on the synchronised chain; `isOwn` tells this installation's record IDs. */
+    classify(chain: LinearChain, isOwn: (recordIdHex: string) => boolean): PhaseState;
+    /** The signed record on the chain's head (§9.3: rebuilt on a new head, never re-sent as it was). */
+    build(chain: LinearChain): Promise<Uint8Array> | Uint8Array;
+    /**
+     * False for a phase whose record depends on more than the head, such as a
+     * KEY_EPOCH and its frontier (§9.3): a pending record is rebuilt on every
+     * attempt, even on the head it was built on. An accepted one is still
+     * recognised by its journaled record ID.
+     */
+    readonly resend?: boolean;
+}
+export interface PhaseOutcome {
+    readonly state: PhaseState | "refused";
+    readonly chain: LinearChain;
+    /** The NACK code of a refused phase. */
+    readonly code?: string;
+    readonly recordId?: ControlRecordId;
+}
+/**
+ * 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 declare function runControlPhase(storage: IdentityStorage, channel: IdentityChannel, journal: OperationJournal, operation: string, spec: ControlPhaseSpec): Promise<PhaseOutcome>;
+/** The DEKs this client holds for `chain`'s epochs, each checked against its commitment. */
+export declare function heldDeks(secrets: SecretStore, chain: LinearChain): Promise<Map<string, ResourceDEK>>;
+/** Stores the DEK of `epoch` (secret first) and links the epoch rows to it (LFCP-034). */
+export declare function storeDek(storage: IdentityStorage, secrets: SecretStore, chain: LinearChain, epoch: DataEpoch, dek: ResourceDEK): Promise<void>;
+/**
+ * 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 declare function fetchDeks(storage: IdentityStorage, secrets: SecretStore, channel: IdentityChannel, chain: LinearChain, recipient: Installation): Promise<Map<string, ResourceDEK>>;
+/** Every Principal with `holds(P, 1)` at the head (W §19, §25.2): the reader set, by ID. */
+export declare function readersAt(state: LinearChain["state"]): readonly PrincipalDescriptor[];
+export interface KeyDelivery {
+    /** Packages sealed and acknowledged now, as (epoch, recipient hex). */
+    readonly sent: readonly {
+        readonly epoch: DataEpoch;
+        readonly recipient: string;
+    }[];
+    /** Already in the ledger (§9.2 Package: complete). */
+    readonly complete: number;
+    /** Recipients that are not readers at the head, or packages the coordinator refused. */
+    readonly skipped: readonly {
+        readonly recipient: string;
+        readonly reason: string;
+    }[];
+}
+/**
+ * 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 declare function deliverKeys(options: {
+    readonly channel: IdentityChannel;
+    readonly ledger: PackageLedger;
+    readonly chain: LinearChain;
+    readonly sender: Signer;
+    readonly recipients: readonly PrincipalDescriptor[];
+    readonly deks: ReadonlyMap<string, ResourceDEK>;
+    readonly resend?: ReadonlyMap<string, ReadonlySet<string>>;
+}): Promise<KeyDelivery>;
+/**
+ * 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 declare function loadIdentityDocument(options: {
+    readonly channel: IdentityChannel;
+    readonly chain: LinearChain;
+    readonly deks: ReadonlyMap<string, ResourceDEK>;
+    readonly doc: IdentityDocumentPort;
+}): Promise<IdentityDocumentLoad>;
+/** What loadIdentityDocument learned besides the document. */
+export interface IdentityDocumentLoad {
+    /** Each actor's latest accepted unit (by Principal hex): the next unit's previous (W §26.2). */
+    readonly latest: ReadonlyMap<string, {
+        readonly seq: bigint;
+        readonly unitId: DataUnitId;
+    }>;
+    /**
+     * The units the wire accepted whose change the document did not take,
+     * after every change it could: refused by its admission (IDENTITY-PROFILE-01
+     * §3), or held for a change it never got (SOP §14.1). The port does not
+     * tell the two apart. In delivery order; empty when the document holds
+     * every unit.
+     */
+    readonly unapplied: readonly {
+        readonly actor: PrincipalId;
+        readonly seq: bigint;
+        readonly unitId: DataUnitId;
+    }[];
+}
+/** The Genesis owner of a chain: the root of an Identity Resource (§2.3). */
+export declare function genesisOwner(chain: LinearChain): 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 declare function sealIdentityUnit(options: {
+    readonly storage: IdentityStorage;
+    readonly chain: LinearChain;
+    readonly deks: ReadonlyMap<string, ResourceDEK>;
+    readonly signer: Signer;
+    readonly doc: IdentityDocumentPort;
+    readonly latest: IdentityDocumentLoad["latest"];
+    readonly intents: readonly IdentityIntent[];
+    /** The sequence to use instead of a reservation (a pairing device shared by installations, §5.3). */
+    readonly seq?: bigint;
+}): Promise<Uint8Array>;
+/**
+ * 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 declare function withoutEquivocations<T extends {
+    readonly bytes: Uint8Array;
+    readonly parsed: Parsed<DataUnitPayload>;
+}>(chain: LinearChain, units: readonly T[]): T[];
+/**
+ * What became of a flow's unit of display data in the Identity Resource:
+ * none needed, written (`committed-own`), found already written by another
+ * writer when the unit was built (`complete`, nothing sent), refused by the
+ * coordinator with `code`, or not sent because the coordinator was
+ * unreachable. `refused` and `unreachable` leave the flow's operation open.
+ */
+export interface DocumentWrite {
+    readonly state: "none" | "committed-own" | "complete" | "refused" | "unreachable";
+    readonly code?: string;
+}
+/**
+ * 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 declare function runUnitPhase(channel: IdentityChannel, journal: OperationJournal, operation: string, spec: {
+    readonly id: string;
+    readonly resource: ResourceId;
+    /**
+     * The unit to send, built on the current state; null when that state
+     * already holds the phase's effect, written by another hand: the phase is
+     * then `complete` and nothing is sent.
+     */
+    readonly build: () => Promise<Uint8Array | null>;
+    /**
+     * Refusals after which the phase's intent is written again as a new unit
+     * on the current state, e.g. STALE_DATA_EPOCH after a rotation (W §19.1);
+     * the refused bytes are kept in the phase as stale, never sent again.
+     */
+    readonly rebuildOn?: readonly string[];
+    /**
+     * A phase an earlier run left refused, whatever the code, is written
+     * again once as a new unit on the current state: how a flow that
+     * reported the refusal resumes the write (the refused bytes are kept as
+     * stale, never sent again).
+     */
+    readonly rebuildRefused?: boolean;
+}): Promise<{
+    readonly state: "committed-own" | "complete" | "refused";
+    readonly code?: string;
+}>;
+//# sourceMappingURL=context.d.ts.map