@openlfcp/client 0.2.2 → 0.3.1

package/dist/identity/resource.d.ts

@@ -0,0 +1,74 @@
+import { type PrincipalId, type ResourceId } from "@openlfcp/core";
+import type { SecretStore } from "@openlfcp/storage";
+import { type IdentityStorage, type Installation } from "./context.js";
+import type { FlowOptions } from "./devices.js";
+import { type IdentityDocumentPort, type RosterEntryValue } from "./document.js";
+import { type IdentityNetwork } from "./network.js";
+import type { LinearChain } from "./phases.js";
+/** The Identity Resource recorded as this installation's identity (W §86), if any. */
+export declare function localIdentityResource(storage: Pick<IdentityStorage, "localMarks">): Promise<ResourceId | undefined>;
+/** Records `I` as this installation's identity. */
+export declare function setLocalIdentityResource(storage: Pick<IdentityStorage, "commit">, identity: ResourceId): Promise<void>;
+/** The document port of an Identity Resource, made once its ID and root are known. */
+export type IdentityDocumentFactory = (identity: ResourceId, root: PrincipalId) => IdentityDocumentPort;
+export interface CreateIdentityResourceOptions {
+    /** The installation `P`, a root without devices (W §7.2 N1). */
+    readonly installation: Installation;
+    readonly storage: IdentityStorage;
+    readonly secrets: SecretStore;
+    readonly network: IdentityNetwork;
+    /** The default server: route, coordinator and host of `I`. */
+    readonly url: string;
+    /** This installation's label for `devices[p:<P>]`. */
+    readonly label: string;
+    readonly platform?: string;
+    /** The local Resource list for the roster. */
+    readonly roster: readonly {
+        readonly resource: ResourceId;
+        readonly entry: RosterEntryValue;
+    }[];
+    readonly document: IdentityDocumentFactory;
+    /** RFC 3339 UTC time for `added_at`; omitted when absent. */
+    readonly addedAt?: string;
+    readonly now: () => number;
+}
+export type CreatedIdentityResource = {
+    readonly kind: "created";
+    readonly identity: ResourceId;
+    readonly chain: LinearChain;
+    readonly document: IdentityDocumentPort;
+    readonly operation: string;
+}
+/** §5.1 step 1: the default server's READY does not list identity-01. */
+ | {
+    readonly kind: "unsupported";
+}
+/** The coordinator refused hosting or a unit: the operation is abandoned. */
+ | {
+    readonly kind: "refused";
+    readonly code: string;
+}
+/** The coordinator could not be reached: resume with resumeIdentityCreation. */
+ | {
+    readonly kind: "unavailable";
+    readonly operation: string;
+    readonly reason: string;
+};
+/** §5.1: creates and hosts `I`, journaled; resumes an open creation first. */
+export declare function createIdentityResource(options: CreateIdentityResourceOptions): Promise<CreatedIdentityResource>;
+/** Sends what an open creation has not sent yet, from its journaled exact bytes. */
+export declare function resumeIdentityCreation(options: Omit<CreateIdentityResourceOptions, "roster" | "label">, operation: string): Promise<CreatedIdentityResource>;
+export interface IdentityFlowOptions extends FlowOptions {
+    /** The Identity Resource; default: the one recorded locally, at its chain's coordinator. */
+    readonly identity?: {
+        readonly resource: ResourceId;
+        readonly url: string;
+    };
+    readonly document: IdentityDocumentFactory;
+}
+/** The Identity Resource of this installation and its coordinator. */
+export declare function identityTarget(o: Pick<IdentityFlowOptions, "identity" | "storage">): Promise<{
+    readonly resource: ResourceId;
+    readonly url: string;
+}>;
+//# sourceMappingURL=resource.d.ts.map

package/dist/identity/resource.js

@@ -0,0 +1,201 @@
+import { dataEpoch, fromHex, generateResourceId, resourceId, secureRandom, toHex, } from "@openlfcp/core";
+import { dekCommitment, generateResourceDEK } from "@openlfcp/crypto";
+import { signControlRecord, validateControlChain } from "@openlfcp/wire";
+import { createDataUnit } from "../data-unit.js";
+import { loadControlChain } from "../storage.js";
+import { fetchDeks, loadIdentityDocument, runUnitPhase, storeDek, syncChain, } from "./context.js";
+import { IDENTITY_PROFILE, identityPlaintextCodec, principalRefOf, resourceRef, } from "./document.js";
+import { newOperationId, OperationJournal, phaseOf, } from "./journal.js";
+import { ChannelPool, IDENTITY_EXTENSION, IdentityUnavailable, } from "./network.js";
+/**
+ * Creating the Identity Resource of an existing installation
+ * (IDENTITY-PROFILE-01 §5.1), on the first "Add my other device…".
+ *
+ * The installation's Principal `P` becomes the root: Genesis with owner `P`
+ * (no field 5), profile org.openlfcp.identity.v1, the default server as
+ * route and coordinator; RESOURCE_HOST; then the initial change (§2.2) in
+ * the root's Data Unit with actor sequence 1 and the fill change (roster
+ * from the local Resource list, `devices[p:<P>]`) in sequence 2. The
+ * Genesis, both units and the epoch-0 DEK are persisted before anything is
+ * sent, and re-sent as exact bytes after a crash: the initial change is
+ * never created twice (§2.2). A run that cannot obtain actor sequence 1
+ * for the new Resource abandons it and creates another.
+ */
+const IDENTITY_MARK = "identity:resource";
+/** The Identity Resource recorded as this installation's identity (W §86), if any. */
+export async function localIdentityResource(storage) {
+    const v = await storage.localMarks.get(IDENTITY_MARK);
+    return v === undefined ? undefined : resourceId(fromHex(v));
+}
+/** Records `I` as this installation's identity. */
+export async function setLocalIdentityResource(storage, identity) {
+    const r = await storage.commit([
+        { op: "put-local-mark", key: IDENTITY_MARK, value: toHex(identity) },
+    ]);
+    if (!r.ok)
+        throw new Error(`the identity was not recorded: ${r.reason}`);
+}
+/** §5.1: creates and hosts `I`, journaled; resumes an open creation first. */
+export async function createIdentityResource(options) {
+    const journal = new OperationJournal(options.storage);
+    const open = (await journal.list({ kind: "create-identity", status: "open" }))[0];
+    if (open !== undefined)
+        return resumeIdentityCreation(options, open.id);
+    const pool = new ChannelPool(options.network);
+    try {
+        const channel = await pool.get(options.installation.signer, options.url);
+        if (!channel.extensions.includes(IDENTITY_EXTENSION))
+            return { kind: "unsupported" };
+    }
+    catch (e) {
+        if (e instanceof IdentityUnavailable)
+            return { kind: "unavailable", operation: "", reason: e.message };
+        throw e;
+    }
+    finally {
+        pool.closeAll();
+    }
+    for (;;) {
+        const id = await prepare(options, journal);
+        if (id !== undefined)
+            return resumeIdentityCreation(options, id);
+    }
+}
+/**
+ * Builds Genesis, the epoch-0 DEK and both units and journals them before
+ * anything is sent. Undefined when actor sequence 1 was not available for
+ * the new Resource (it is then abandoned unhosted).
+ */
+async function prepare(options, journal) {
+    const P = options.installation.signer;
+    const I = generateResourceId();
+    const dek = generateResourceDEK();
+    const genesis = signControlRecord({ resourceId: I, controlSeq: 0n, prevControlId: null }, {
+        type: "GENESIS",
+        dataProfile: IDENTITY_PROFILE,
+        owner: P.descriptor,
+        dekCommitment: dekCommitment(I, dataEpoch(0n), dek),
+        endpoints: [{ url: options.url, priority: 0n }],
+        coordinatorUrl: options.url,
+    }, P);
+    const chain = validateControlChain([genesis.bytes]);
+    if (chain.kind !== "linear")
+        throw new Error("the new Genesis does not validate");
+    // The DEK first (LFCP-034), then the chain row that references it.
+    await storeDek(options.storage, options.secrets, chain, dataEpoch(0n), dek);
+    const doc = options.document(I, P.descriptor.principalId);
+    const unit = async (seq, intents, previous) => {
+        const created = await createDataUnit({
+            view: chain,
+            controlHead: chain.state.head,
+            actor: P,
+            dek,
+            sequences: options.storage.actorSequences,
+            previousUnitId: previous,
+            profile: identityPlaintextCodec,
+            value: doc.write({ signer: P.descriptor.principalId, actorSeq: seq, writerClass: "root" }, intents),
+        });
+        return created.seq === seq ? created : undefined;
+    };
+    const initial = await unit(1n, [{ intent: "identity.initialize" }], null);
+    if (initial === undefined)
+        return undefined;
+    const fill = await unit(2n, [
+        ...options.roster.map((r) => ({
+            intent: "roster.put",
+            key: resourceRef(r.resource),
+            entry: r.entry,
+        })),
+        {
+            intent: "device.put",
+            key: principalRefOf(P.descriptor.principalId),
+            entry: {
+                label: options.label,
+                kind: 0,
+                ...(options.platform === undefined ? {} : { platform: options.platform }),
+                ...(options.addedAt === undefined ? {} : { added_at: options.addedAt }),
+            },
+        },
+    ], initial.unitId);
+    if (fill === undefined)
+        return undefined;
+    const id = newOperationId("create-identity", secureRandom(8));
+    const R = toHex(I);
+    await journal.begin({
+        id,
+        kind: "create-identity",
+        createdAt: options.now(),
+        intent: { identity: R, url: options.url, label: options.label },
+        phases: [
+            { id: "host", kind: "host", resource: R, state: "pending", bytes: toHex(genesis.bytes) },
+            { id: "unit:1", kind: "unit", resource: R, state: "pending", bytes: toHex(initial.bytes) },
+            { id: "unit:2", kind: "unit", resource: R, state: "pending", bytes: toHex(fill.bytes) },
+        ],
+    });
+    return id;
+}
+/** Sends what an open creation has not sent yet, from its journaled exact bytes. */
+export async function resumeIdentityCreation(options, operation) {
+    const journal = new OperationJournal(options.storage);
+    let op = await journal.load(operation);
+    const I = resourceId(fromHex(op.intent.identity));
+    const pool = new ChannelPool(options.network);
+    try {
+        const channel = await pool.get(options.installation.signer, op.intent.url);
+        const host = phaseOf(op, "host");
+        if (host.state !== "committed-own") {
+            const answer = await channel.host(fromHex(host.bytes));
+            // W §39: the Genesis a server already hosts is answered with RESOURCE_HOSTED again.
+            if (answer.kind === "nack") {
+                await journal.putPhase(operation, { ...host, state: "refused", code: answer.code });
+                await journal.setStatus(operation, "abandoned");
+                return { kind: "refused", code: answer.code };
+            }
+            op = await journal.putPhase(operation, { ...host, state: "committed-own" });
+        }
+        for (const id of ["unit:1", "unit:2"]) {
+            const r = await runUnitPhase(channel, journal, operation, {
+                id,
+                resource: I,
+                build: () => Promise.reject(new Error("the unit is journaled")),
+            });
+            if (r.state === "refused") {
+                await journal.setStatus(operation, "abandoned");
+                return { kind: "refused", code: r.code ?? "refused" };
+            }
+        }
+        const chain = await syncChain(options.storage, channel, I);
+        await setLocalIdentityResource(options.storage, I);
+        await journal.setStatus(operation, "done");
+        const document = options.document(I, chain.state.owner.principalId);
+        // The document as the coordinator holds it (the local port of a resumed run is fresh).
+        await loadIdentityDocument({
+            channel,
+            chain,
+            deks: await fetchDeks(options.storage, options.secrets, channel, chain, options.installation),
+            doc: document,
+        });
+        return { kind: "created", identity: I, chain, document, operation };
+    }
+    catch (e) {
+        if (e instanceof IdentityUnavailable)
+            return { kind: "unavailable", operation, reason: e.message };
+        throw e;
+    }
+    finally {
+        pool.closeAll();
+    }
+}
+/** The Identity Resource of this installation and its coordinator. */
+export async function identityTarget(o) {
+    if (o.identity !== undefined)
+        return o.identity;
+    const resource = await localIdentityResource(o.storage);
+    if (resource === undefined)
+        throw new Error("this installation has no Identity Resource");
+    const chain = await loadControlChain(o.storage, resource);
+    if (chain?.kind !== "linear")
+        throw new Error("the Identity Resource's chain is not stored");
+    return { resource, url: chain.state.route.coordinatorUrl };
+}
+//# sourceMappingURL=resource.js.map

package/dist/identity/revocation.d.ts

@@ -0,0 +1,106 @@
+import { type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type DocumentWrite } from "./context.js";
+import { type FlowOptions } from "./devices.js";
+import { type IdentityChannel } from "./network.js";
+import { type IdentityFlowOptions } from "./resource.js";
+import { type RotationOutcome } from "./rotation.js";
+/**
+ * Revoking a device (IDENTITY-PROFILE-01 §8, decision I4) and the
+ * automatic rotation policy (§8.4).
+ */
+/** What revoking `device` does to one Resource, computed on the post-state (§8.1). */
+export interface ResourcePreview {
+    readonly resource: ResourceId;
+    readonly status: "ok" | "self-dependent" | "already-revoked" | "not-authorized" | "unreachable" | "unsupported" | "conflict";
+    /** Devices active before and suspended after, by the cascade (W §17.5). */
+    readonly suspended: readonly PrincipalId[];
+    /** Whether the revocation removes a reader (W §17.5). */
+    readonly exposing: boolean;
+    /** Whether this installation rotates afterwards (§8.1); else the Resource awaits rotation. */
+    readonly rotator: boolean;
+}
+export interface RevocationPreview {
+    readonly device: PrincipalId;
+    /** The revoker's own chain passes through the device: re-certify first (§8.1). */
+    readonly selfDependent: boolean;
+    readonly resources: readonly ResourcePreview[];
+}
+/**
+ * §8.1: the post-state of revoking `device` in `I` and every reachable
+ * roster Resource: suspended devices, exposure, whether this installation
+ * stays active and who rotates.
+ */
+export declare function previewRevocation(o: IdentityFlowOptions & {
+    readonly device: PrincipalId;
+    readonly reason?: bigint;
+}): Promise<RevocationPreview>;
+/** One Resource's part of a revocation. */
+export interface RevocationResult {
+    readonly resource: ResourceId;
+    readonly revoke: "revoked" | "complete" | "superseded" | "not-authorized"
+    /** The revoker's own chain passes through the device here: re-certify it here first (§8.1). */
+     | "self-dependent" | "refused" | "unreachable" | "unsupported" | "conflict";
+    readonly rotation?: RotationOutcome;
+}
+export type RevokeDeviceResult = {
+    readonly kind: "revoked";
+    readonly operation: string;
+    readonly results: readonly RevocationResult[];
+    /**
+     * §8.2 display: the device's `revoked` flag in the Identity Resource:
+     * `none` when the device has no entry, `complete` when another writer
+     * set the flag. Refused or unreachable leaves the operation open;
+     * revokeDevice with that `operation` writes the flag again.
+     */
+    readonly document: DocumentWrite;
+}
+/** The revoker's chain passes through the device: obtain a fresh chain first (§8.1). */
+ | {
+    readonly kind: "self-dependent";
+}
+/** Only the root or a managing device revokes devices (§8). */
+ | {
+    readonly kind: "not-authorized";
+}
+/** The pair was consumed by a pairing approval (§9.2 Revoke: superseded). */
+ | {
+    readonly kind: "superseded";
+    readonly operation: string;
+}
+/** Revocation needs the Identity Resource's coordinator: an offline "Remove device…" is refused (§8.5). */
+ | {
+    readonly kind: "unavailable";
+    readonly operation?: string;
+    readonly reason: string;
+} | {
+    readonly kind: "conflict";
+};
+/**
+ * §8.2–§8.5: `DEVICE_REVOKE {R, D, r}` in `I`, then in every roster
+ * Resource where this installation may act, each followed by the rotation
+ * when the revocation is exposing there and this installation is the
+ * rotator (else `awaiting-rotation`). A self-retiring device (`D` is this
+ * installation, reason 0) commits the revocations only. Every phase is
+ * journaled and classified by §9.2: a revocation by another hand with
+ * another reason is `complete` and the rotation test still runs.
+ */
+export declare function revokeDevice(o: IdentityFlowOptions & {
+    readonly device: PrincipalId;
+    /** 0 retired, 1 lost, 2 compromised. */
+    readonly reason: 0n | 1n | 2n;
+    /** Resume this operation. */
+    readonly operation?: string;
+}): Promise<RevokeDeviceResult>;
+/**
+ * §8.4 rotation policy: when the Resource holds an exposing revocation
+ * committed after its current epoch opened and this installation is the
+ * rotator, rotate once (covering every such revocation) and seal the new
+ * DEK to every reader; otherwise `awaiting-rotation`, or `not-needed` when
+ * nothing exposing happened since the last rotation.
+ */
+export declare function rotateIfExposed(o: FlowOptions & {
+    readonly channel: IdentityChannel;
+    readonly operation: string;
+    readonly resource: ResourceId;
+}): Promise<RotationOutcome>;
+//# sourceMappingURL=revocation.d.ts.map