@openlfcp/client 0.1.5 → 0.2.0-beta.1

package/dist/invite.js

@@ -1,7 +1,8 @@
-import { bytesEqual, hash32, LfcpError, toHex, } from "@openlfcp/core";
+import { bytesEqual, fromHex, hash32, LfcpError, toHex, } from "@openlfcp/core";
 import { dekCommitment, exportSecretKeyBytes, InvitationSecret, } from "@openlfcp/crypto";
 import { dekSecretRef } from "@openlfcp/storage";
 import { ABILITY, assembleInviteUri, createMessage, ERROR_CODE, invitationPrincipal, parseControlRecord, parseInviteUri, parseKeyPackage, receiveKeyPackage, sealKeyPackage, signControlRecord, validateControlChain, verifyInvitationSecret, verifyKeyPackage, } from "@openlfcp/wire";
+import { clearClaimJournal, journaledDeks, readClaimJournal, writeClaimJournal, } from "./claim-journal.js";
 import { LfcpConnection } from "./connection.js";
 import { queueControlRecord, queueKeyPackage } from "./queue.js";
 import { loadControlChain, saveControlChain } from "./storage.js";
@@ -274,6 +275,16 @@ export async function acceptInvitation(options) {
         // §73: the Invitation Principal authenticates and opens the Resource.
         progress("connecting");
         await s.connect();
+        // LFCP-02-110: a claim of this link whose answer was lost is settled first.
+        const journal = await readClaimJournal(options.storage, R);
+        if (journal !== undefined &&
+            journal.invitationGrantId === toHex(invitation.grantId) &&
+            journal.claimant === toHex(options.claimant.signer.descriptor.principalId)) {
+            progress("claiming-capability", 1);
+            const settled = await settleJournal(s, options, R, journal);
+            if (settled !== "not-committed")
+                return settled;
+        }
         progress("validating-invitation");
         const heads = await openAsInvitee(s, R, invitation.grantId);
         if (heads.length !== 1)
@@ -331,6 +342,18 @@ export async function acceptInvitation(options) {
                 claimant: options.claimant.signer.descriptor,
                 abilities,
             }, claimSigner);
+            // The journal before the claim: a lost answer is resolved from it.
+            await writeClaimJournal(options.storage, options.secrets, R, {
+                v: 1,
+                resourceId: toHex(R),
+                invitationGrantId: toHex(invitation.grantId),
+                claimant: toHex(options.claimant.signer.descriptor.principalId),
+                claim: toHex(claim.bytes),
+                expectedHead: toHex(chain.state.head),
+                chain: chain.records.map((r) => toHex(r.signed.bytes)),
+                epochs: [...deks.keys()],
+                abilities: abilities.map(String),
+            }, deks, exportSecretKeyBytes);
             const answer = await s.request(createMessage("CONTROL_PUT", {
                 resourceId: R,
                 expectedHead: chain.state.head,
@@ -345,6 +368,7 @@ export async function acceptInvitation(options) {
                 if (claimed.kind !== "linear")
                     fail("INVALID_CONTROL_CHAIN", "the acknowledged claim does not validate locally");
                 await persist(options, claimed, deks);
+                await clearClaimJournal(options.storage, R);
                 return Object.freeze({
                     kind: "claimed",
                     resourceId: R,
@@ -352,6 +376,7 @@ export async function acceptInvitation(options) {
                     abilities: Object.freeze([...abilities]),
                     epochs: Object.freeze([...deks.keys()].map((e) => BigInt(e))),
                     attempts: Object.freeze(attempts),
+                    resumed: false,
                 });
             }
             if (answer.type !== "NACK")
@@ -360,13 +385,18 @@ export async function acceptInvitation(options) {
             attempts.push(code);
             const head = answer.body.details;
             // One refresh after a lost race (§73); the coordinator's next answer is final.
-            if (code !== "CONTROL_HEAD_MISMATCH" || attempts.length > 1 || !(head instanceof Uint8Array))
+            if (code !== "CONTROL_HEAD_MISMATCH" ||
+                attempts.length > 1 ||
+                !(head instanceof Uint8Array)) {
+                // A refused claim was not committed: nothing to resume.
+                await clearClaimJournal(options.storage, R);
                 return Object.freeze({
                     kind: "refused",
                     resourceId: R,
                     code,
                     attempts: Object.freeze(attempts),
                 });
+            }
             chain = await fetchChain(s, R, chain.records.map((r) => r.signed.bytes), { head });
         }
     }
@@ -379,6 +409,89 @@ export async function acceptInvitation(options) {
         s.close();
     }
 }
+/**
+ * LFCP-02-110: sends a journaled claim again. A coordinator answers a
+ * record it has already committed with the same ACK (§47, §70): then the
+ * claim landed before and the claimant joins from the journal. Any other
+ * answer means it was not committed: a moved head lets the caller claim
+ * anew ("not-committed"); another refusal is final. A transport stop
+ * throws Unavailable and keeps the journal.
+ */
+async function settleJournal(s, options, R, journal) {
+    const claim = fromHex(journal.claim);
+    const answer = await s.request(createMessage("CONTROL_PUT", {
+        resourceId: R,
+        expectedHead: fromHex(journal.expectedHead),
+        record: claim,
+    }), "the CONTROL_PUT answer")();
+    if (answer.type === "ACK") {
+        const claimed = validateControlChain([...journal.chain.map(fromHex), claim]);
+        if (claimed.kind !== "linear")
+            fail("INVALID_CONTROL_CHAIN", "the journaled claim does not validate locally");
+        const deks = await journaledDeks(options.secrets, R, journal);
+        await persist(options, claimed, deks);
+        await clearClaimJournal(options.storage, R);
+        return Object.freeze({
+            kind: "claimed",
+            resourceId: R,
+            grantId: claimed.state.head,
+            abilities: Object.freeze(journal.abilities.map((a) => BigInt(a))),
+            epochs: Object.freeze([...deks.keys()].map((e) => BigInt(e))),
+            attempts: Object.freeze(["ACK"]),
+            resumed: true,
+        });
+    }
+    if (answer.type !== "NACK")
+        throw new Unavailable(`CONTROL_PUT was answered with ${answer.type}`);
+    await clearClaimJournal(options.storage, R);
+    const code = codeName(answer.body.code);
+    if (code === "CONTROL_HEAD_MISMATCH")
+        return "not-committed";
+    return Object.freeze({
+        kind: "refused",
+        resourceId: R,
+        code,
+        attempts: Object.freeze([code]),
+    });
+}
+/**
+ * Settles a journaled claim without its link, e.g. after a restart
+ * (LFCP-02-110): "claimed" when the claim had landed; "not-claimed" when it
+ * had not (the journal is removed, and the link, still unused, can be
+ * accepted again); "refused" for another refusal; "unavailable" keeps the
+ * journal for a later try; "none" when no claim is journaled.
+ */
+export async function resumeInvitationClaim(options) {
+    const R = options.resourceId;
+    const journal = await readClaimJournal(options.storage, R);
+    if (journal === undefined)
+        return Object.freeze({ kind: "none", resourceId: R });
+    const s = new ClaimSession({
+        url: options.url,
+        signer: options.claimant.signer,
+        now: options.now,
+        ...(options.webSocket === undefined ? {} : { webSocket: options.webSocket }),
+    }, options.timeout ?? NEVER);
+    try {
+        await s.connect();
+        const settled = await settleJournal(s, options, R, journal);
+        return settled === "not-committed"
+            ? Object.freeze({ kind: "not-claimed", resourceId: R })
+            : settled;
+    }
+    catch (e) {
+        if (e instanceof Unavailable)
+            return Object.freeze({ kind: "unavailable", resourceId: R, reason: e.message });
+        throw e;
+    }
+    finally {
+        s.close();
+    }
+}
+/** Gives up a journaled claim (the user declined to retry it): its journal is removed. */
+export async function abandonInvitationClaim(storage, resource) {
+    await clearClaimJournal(storage, resource);
+}
 /** The claimant's storage: the chain with its grant, then each DEK before the row that names it (LFCP-034). */
 async function persist(options, chain, deks) {
     const R = chain.state.resourceId;

package/dist/outbound.d.ts

@@ -1,5 +1,5 @@
 import { type ActorSequence, type ControlRecordId, type DataEpoch, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
-import type { LfcpStorage, OutboundBlock, OutboundItem, OutboundKind } from "@openlfcp/storage";
+import type { LfcpStorage, OutboundBlock, OutboundItem, OutboundKind, StorageWrite } from "@openlfcp/storage";
 import { type ControlView, type HaveVector, type LfcpMessage, type WireErrorName } from "@openlfcp/wire";
 /**
  * The pending outbound queue and its sync state (LFCP-036): a
@@ -66,6 +66,20 @@ export interface AckOutcome {
     /** False when the ACK answers no message of this session (matched by object ID only). */
     readonly correlated: boolean;
 }
+/** An item an ACK removed from the queue, for writes that go with its removal. */
+export interface AckedItem {
+    readonly itemId: Hash32;
+    readonly resourceId: ResourceId;
+    readonly kind: OutboundKind;
+}
+/**
+ * Writes committed in the same transaction as an ACK's dequeue, from the
+ * items it removed and what the ACK established (e.g. batch acceptance).
+ */
+export type AckWrites = (acked: readonly AckedItem[], ack: {
+    readonly durability: bigint;
+    readonly correlated: boolean;
+}) => Promise<readonly StorageWrite[]>;
 /** A blocked item as surfaced to the application. */
 export interface BlockedItem {
     readonly itemId: Hash32;
@@ -186,9 +200,10 @@ export declare class OutboundQueue {
      * An ACK (§59): removes the queued items whose IDs it names (field 1),
      * and records them in the Resource's sync state. Items of the
      * acknowledged message it does not name stay queued. Idempotent: a
-     * repeated ACK, or one for items already gone, changes nothing.
+     * repeated ACK, or one for items already gone, changes nothing. `also`
+     * adds writes to the dequeue's transaction.
      */
-    onAck(message: LfcpMessage<"ACK">, now: string): Promise<AckOutcome>;
+    onAck(message: LfcpMessage<"ACK">, now: string, also?: AckWrites): Promise<AckOutcome>;
     /**
      * A NACK (§60) of one of this session's messages. Per-object codes on a
      * message of several objects resend each object alone, to learn which one

package/dist/outbound.js

@@ -294,14 +294,16 @@ export class OutboundQueue {
      * An ACK (§59): removes the queued items whose IDs it names (field 1),
      * and records them in the Resource's sync state. Items of the
      * acknowledged message it does not name stay queued. Idempotent: a
-     * repeated ACK, or one for items already gone, changes nothing.
+     * repeated ACK, or one for items already gone, changes nothing. `also`
+     * adds writes to the dequeue's transaction.
      */
-    async onAck(message, now) {
+    async onAck(message, now, also) {
         const flight = this.#land(message.correlationId);
         const named = message.body.objectIds ?? [];
         const durability = message.body.durable === true ? this.#durability : 0n;
         const requestType = message.body.requestType;
         const acked = [];
+        const ackedItems = [];
         const below = [];
         const byResource = new Map();
         for (const id of named) {
@@ -317,6 +319,7 @@ export class OutboundQueue {
                 continue;
             }
             acked.push(item.itemId);
+            ackedItems.push({ itemId: item.itemId, resourceId: item.resourceId, kind: item.kind });
             const key = toHex(item.resourceId);
             byResource.set(key, [...(byResource.get(key) ?? []), item.itemId]);
             this.#forget(item.itemId);
@@ -345,6 +348,8 @@ export class OutboundQueue {
                 },
             });
         }
+        if (also !== undefined && ackedItems.length > 0)
+            writes.push(...(await also(ackedItems, { durability, correlated: flight !== undefined })));
         await this.#commit(writes);
         const notCovered = flight?.itemIds.filter((id) => !acked.some((a) => bytesEqual(a, id)) && !below.some((b) => bytesEqual(b, id))) ?? [];
         const stillQueued = [];

package/dist/queue.d.ts

@@ -19,6 +19,8 @@ export declare const outboundItem: (kind: OutboundKind, itemId: Hash32, resource
  * (adoptStoredDeks) with no network round trip.
  */
 export declare function queueKeyEpoch(storage: Pick<LfcpStorage, "commit">, secrets: SecretStore, rotation: EpochRotation, also?: readonly StorageWrite[]): Promise<Hash32>;
+/** The writes that store a sealed Key Package (§25) and queue it, for one commit with others. */
+export declare function keyPackageWrites(bytes: Uint8Array): StorageWrite[];
 /** Stores a sealed Key Package (§25) and queues it for KEY_PACKAGE_PUT. */
 export declare function queueKeyPackage(storage: Pick<LfcpStorage, "commit">, bytes: Uint8Array, also?: readonly StorageWrite[]): Promise<Hash32>;
 /** Stores a sealed Snapshot (§29) with its selection metadata and queues it for SNAPSHOT_PUT. */
@@ -35,4 +37,6 @@ export declare function createQueuedSnapshot<T>(storage: Pick<LfcpStorage, "snap
  * validated chain contains it (saveControlChain).
  */
 export declare function queueControlRecord(storage: Pick<LfcpStorage, "commit">, bytes: Uint8Array, also?: readonly StorageWrite[]): Promise<Hash32>;
+/** The write that queues a signed Control Record for CONTROL_PUT, for one commit with others. */
+export declare function controlRecordWrites(bytes: Uint8Array): StorageWrite[];
 //# sourceMappingURL=queue.d.ts.map

package/dist/queue.js

@@ -39,12 +39,12 @@ export async function queueKeyEpoch(storage, secrets, rotation, also = []) {
     await secrets.put(dekSecretRef(resource, rotation.epoch), exportSecretKeyBytes(rotation.dek));
     return queueControlRecord(storage, rotation.bytes, also);
 }
-/** Stores a sealed Key Package (§25) and queues it for KEY_PACKAGE_PUT. */
-export async function queueKeyPackage(storage, bytes, also = []) {
+/** The writes that store a sealed Key Package (§25) and queue it, for one commit with others. */
+export function keyPackageWrites(bytes) {
     const parsed = parseKeyPackage(bytes);
     const p = parsed.payload;
     const id = hash32(parsed.signed.id);
-    await commit(storage, [
+    return [
         {
             op: "put-key-package",
             row: {
@@ -57,9 +57,12 @@ export async function queueKeyPackage(storage, bytes, also = []) {
             },
         },
         { op: "enqueue", item: outboundItem("key-package", id, p.resourceId, parsed.signed.bytes) },
-        ...also,
-    ]);
-    return id;
+    ];
+}
+/** Stores a sealed Key Package (§25) and queues it for KEY_PACKAGE_PUT. */
+export async function queueKeyPackage(storage, bytes, also = []) {
+    await commit(storage, [...keyPackageWrites(bytes), ...also]);
+    return hash32(parseKeyPackage(bytes).signed.id);
 }
 /** Stores a sealed Snapshot (§29) with its selection metadata and queues it for SNAPSHOT_PUT. */
 export async function queueSnapshot(storage, bytes, also = []) {
@@ -100,17 +103,20 @@ export async function createQueuedSnapshot(storage, options, also = []) {
  * validated chain contains it (saveControlChain).
  */
 export async function queueControlRecord(storage, bytes, also = []) {
+    await commit(storage, [...controlRecordWrites(bytes), ...also]);
+    return hash32(parseControlRecord(bytes).signed.id);
+}
+/** The write that queues a signed Control Record for CONTROL_PUT, for one commit with others. */
+export function controlRecordWrites(bytes) {
     const parsed = parseControlRecord(bytes);
     if (parsed.payload.prevControlId === null)
         throw new Error("a Genesis record is hosted with RESOURCE_HOST, not CONTROL_PUT");
     const id = hash32(parsed.signed.id);
-    await commit(storage, [
+    return [
         {
             op: "enqueue",
             item: outboundItem("control-record", id, parsed.payload.resourceId, parsed.signed.bytes),
         },
-        ...also,
-    ]);
-    return id;
+    ];
 }
 //# sourceMappingURL=queue.js.map

package/dist/receipts.d.ts

@@ -0,0 +1,60 @@
+import { type DataUnitId, type ResourceId } from "@openlfcp/core";
+import type { LfcpStorage, StorageWrite } from "@openlfcp/storage";
+/**
+ * Commit receipts (SDK-SECTIONS-INTEGRATION-01 §3, LFCP-02-025): the
+ * durable record that a batch of intents was committed locally, written in
+ * the same storage transaction as its Data Units, outbound entries and
+ * profile checkpoint (commitOperation). A receipt is kept as a local mark
+ * under its Resource and operation ID until the caller releases it.
+ *
+ * Released before its batch is final (accepted or rejected, §4.1), a
+ * receipt is no longer the caller's: receiptOf and receiptsOf no longer
+ * return it. Its batch is still reported (batchStatuses, the status
+ * snapshot) until it is final, and then forgotten; for that the receipt is
+ * kept under a `released-batch:` mark.
+ */
+/** §3.2: what a committed batch produced. */
+export interface Receipt {
+    readonly operationId: string;
+    /** The Data Unit IDs of the batch, in the order of their changes. */
+    readonly unitIds: readonly DataUnitId[];
+    /** The nodes the batch writes (and the section when it writes the title). */
+    readonly affectedNodeIds: readonly string[];
+    /** The local document's heads after the commit, sorted, as one opaque string. */
+    readonly modelRevision: string;
+    /** §3.3: SHA-256 (hex) of the batch's canonical form. */
+    readonly intentsHash: string;
+    /** Always true: a receipt exists only for a durable commit. */
+    readonly durable: true;
+}
+/** §3.3: an operation ID that already has a receipt for different intents. A local SDK error. */
+export declare class OperationIdReusedError extends Error {
+    readonly operationId: string;
+    readonly code = "OPERATION_ID_REUSED";
+    constructor(operationId: string);
+}
+/**
+ * §3.3: SHA-256 (hex) of the deterministic CBOR (RFC 8949 §4.2.1) of the
+ * list of intents in order, each a map from its field names to their
+ * values, Text as given, nothing normalized.
+ */
+export declare function intentsHash(intents: readonly unknown[]): string;
+/** The local-mark write that stores `receipt` (for the commit's transaction). */
+export declare function receiptWrite(resource: ResourceId, receipt: Receipt): StorageWrite;
+/** §3.4: the receipt of an operation, definitive across restarts; undefined when nothing was committed. */
+export declare function receiptOf(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId, operationId: string): Promise<Receipt | undefined>;
+/** The receipt of a released batch that is not final yet; undefined otherwise. */
+export declare function releasedReceiptOf(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId, operationId: string): Promise<Receipt | undefined>;
+/** The receipts of a Resource's released batches that are not final yet. */
+export declare function releasedReceiptsOf(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId): Promise<Receipt[]>;
+/** Keeps a released receipt for its batch's status (or, with null, forgets it). */
+export declare function releasedWrite(resource: ResourceId, operationId: string, receipt: Receipt | null): StorageWrite;
+/** Every receipt of a Resource that is not released yet. */
+export declare function receiptsOf(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId): Promise<Receipt[]>;
+/**
+ * §3.5: forgets a receipt the caller has finished with. Its batch status
+ * goes with it when the batch is final (accepted or rejected); otherwise
+ * the batch is still reported until it is final.
+ */
+export declare function releaseReceipt(storage: Pick<LfcpStorage, "commit" | "localMarks">, resource: ResourceId, operationId: string): Promise<void>;
+//# sourceMappingURL=receipts.d.ts.map

package/dist/receipts.js

@@ -0,0 +1,118 @@
+import { dataUnitId, fromHex, toHex } from "@openlfcp/core";
+import { sha256 } from "@openlfcp/crypto";
+import { cborMap, encode } from "@openlfcp/wire/cbor";
+import { releaseWrites } from "./batch-status.js";
+/** §3.3: an operation ID that already has a receipt for different intents. A local SDK error. */
+export class OperationIdReusedError extends Error {
+    operationId;
+    code = "OPERATION_ID_REUSED";
+    constructor(operationId) {
+        super(`operation ${operationId} already committed different intents (§3.3)`);
+        this.operationId = operationId;
+        this.name = "OperationIdReusedError";
+    }
+}
+const PREFIX = "receipt:";
+const markKey = (resource, operationId) => `${PREFIX}${toHex(resource)}:${operationId}`;
+const RELEASED = "released-batch:";
+const releasedKey = (resource, operationId) => `${RELEASED}${toHex(resource)}:${operationId}`;
+/** A plain value as the CBOR data model: objects become maps, absent fields are left out. */
+function cbor(value, depth = 0) {
+    if (depth > 64)
+        throw new Error("an intent nests too deep to hash");
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value))
+            throw new Error(`an intent holds a non-integer number: ${value}`);
+        return value;
+    }
+    if (typeof value === "bigint" || value instanceof Uint8Array)
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => cbor(v, depth + 1));
+    if (typeof value === "object")
+        return cborMap(Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => [k, cbor(v, depth + 1)]));
+    throw new Error(`an intent holds a ${typeof value}, which has no canonical form`);
+}
+/**
+ * §3.3: SHA-256 (hex) of the deterministic CBOR (RFC 8949 §4.2.1) of the
+ * list of intents in order, each a map from its field names to their
+ * values, Text as given, nothing normalized.
+ */
+export function intentsHash(intents) {
+    return toHex(sha256(encode(cbor(intents))));
+}
+/** The receipt as stored in a local mark. */
+function storedReceipt(receipt) {
+    const stored = {
+        operationId: receipt.operationId,
+        unitIds: receipt.unitIds.map((u) => toHex(u)),
+        affectedNodeIds: [...receipt.affectedNodeIds],
+        modelRevision: receipt.modelRevision,
+        intentsHash: receipt.intentsHash,
+    };
+    return JSON.stringify(stored);
+}
+/** The local-mark write that stores `receipt` (for the commit's transaction). */
+export function receiptWrite(resource, receipt) {
+    return {
+        op: "put-local-mark",
+        key: markKey(resource, receipt.operationId),
+        value: storedReceipt(receipt),
+    };
+}
+const parse = (raw) => {
+    const s = JSON.parse(raw);
+    return Object.freeze({
+        operationId: s.operationId,
+        unitIds: Object.freeze(s.unitIds.map((u) => dataUnitId(fromHex(u)))),
+        affectedNodeIds: Object.freeze([...s.affectedNodeIds]),
+        modelRevision: s.modelRevision,
+        intentsHash: s.intentsHash,
+        durable: true,
+    });
+};
+/** §3.4: the receipt of an operation, definitive across restarts; undefined when nothing was committed. */
+export async function receiptOf(storage, resource, operationId) {
+    const raw = await storage.localMarks.get(markKey(resource, operationId));
+    return raw === undefined ? undefined : parse(raw);
+}
+/** The receipt of a released batch that is not final yet; undefined otherwise. */
+export async function releasedReceiptOf(storage, resource, operationId) {
+    const raw = await storage.localMarks.get(releasedKey(resource, operationId));
+    return raw === undefined ? undefined : parse(raw);
+}
+/** The receipts of a Resource's released batches that are not final yet. */
+export async function releasedReceiptsOf(storage, resource) {
+    return (await storage.localMarks.list(`${RELEASED}${toHex(resource)}:`)).map((m) => parse(m.value));
+}
+/** Keeps a released receipt for its batch's status (or, with null, forgets it). */
+export function releasedWrite(resource, operationId, receipt) {
+    return {
+        op: "put-local-mark",
+        key: releasedKey(resource, operationId),
+        value: receipt === null ? null : storedReceipt(receipt),
+    };
+}
+/** Every receipt of a Resource that is not released yet. */
+export async function receiptsOf(storage, resource) {
+    return (await storage.localMarks.list(`${PREFIX}${toHex(resource)}:`)).map((m) => parse(m.value));
+}
+/**
+ * §3.5: forgets a receipt the caller has finished with. Its batch status
+ * goes with it when the batch is final (accepted or rejected); otherwise
+ * the batch is still reported until it is final.
+ */
+export async function releaseReceipt(storage, resource, operationId) {
+    const receipt = await receiptOf(storage, resource, operationId);
+    const r = await storage.commit([
+        { op: "put-local-mark", key: markKey(resource, operationId), value: null },
+        ...(receipt === undefined ? [] : await releaseWrites(storage, resource, receipt)),
+    ]);
+    if (!r.ok)
+        throw new Error(`the receipt was not released: ${r.reason}`);
+}
+//# sourceMappingURL=receipts.js.map

package/dist/revoke.d.ts

@@ -0,0 +1,71 @@
+import { type ControlRecordId, type DataEpoch, type PrincipalId } from "@openlfcp/core";
+import type { ResourceDEK } from "@openlfcp/crypto";
+import { type ChainResult, type HaveVector, type Signer } from "@openlfcp/wire";
+/**
+ * Removing a member's access (LFCP-02-060, LFCP-WIRE-01 §17.3, §19, §25):
+ * every active grant naming the member that the revoker may revoke is
+ * revoked, which also deactivates the grants delegated from it (§17.2);
+ * then, when the member has no read access left, the Data Epoch is rotated
+ * with a fresh DEK (§19, reason "member revoked"), and the new DEK goes in
+ * Key Packages to every remaining reader, so the member cannot read new
+ * data. Every record is built on the validated head and checked by
+ * extending the chain before anything is queued.
+ */
+type Linear = Extract<ChainResult, {
+    kind: "linear";
+}>;
+/** A grant naming the member that the revoker may not revoke: the member keeps access through it. */
+export interface RemainingPath {
+    readonly grantId: ControlRecordId;
+    readonly issuer: PrincipalId;
+    readonly abilities: readonly string[];
+}
+/** What a revocation writes, before it is queued. */
+export interface RevocationPlan {
+    /** The grants revoked, in record order. */
+    readonly revoked: readonly ControlRecordId[];
+    /** Grants delegated from them that the revocations deactivate (§17.2). */
+    readonly deactivated: readonly ControlRecordId[];
+    /** The signed Control Records in order: the revocations, then the Key Epoch if any. */
+    readonly records: readonly {
+        readonly recordId: ControlRecordId;
+        readonly bytes: Uint8Array;
+    }[];
+    /** The new epoch and its DEK, when the epoch is rotated. */
+    readonly rotation: {
+        readonly epoch: DataEpoch;
+        readonly dek: ResourceDEK;
+    } | null;
+    /** Sealed Key Packages of the new DEK, one per remaining reader. */
+    readonly keyPackages: readonly Uint8Array[];
+    /** The readers who receive them. */
+    readonly recipients: readonly PrincipalId[];
+    readonly remainingPaths: readonly RemainingPath[];
+}
+export type RevocationRefusal = 
+/** The member is the Resource's owner: ownership is transferred, never revoked. */
+"would-remove-owner"
+/** No active grant names the member. */
+ | "not-member"
+/** The revoker may revoke none of the member's grants, or may not rotate the epoch. */
+ | "not-authorized";
+export declare class RevocationRefused extends Error {
+    readonly reason: RevocationRefusal;
+    constructor(reason: RevocationRefusal, message: string);
+}
+/**
+ * Plans the removal of `subject` by `revoker` on the validated chain
+ * `view`. `frontier` is the closing epoch's accepted final frontier (the
+ * local Have). With `rotate: false`, or when the member keeps read access
+ * through a remaining path, the epoch is not rotated. Throws
+ * RevocationRefused.
+ */
+export declare function planRevocation(options: {
+    readonly view: Linear;
+    readonly revoker: Signer;
+    readonly subject: PrincipalId;
+    readonly frontier: HaveVector;
+    readonly rotate?: boolean;
+}): Promise<RevocationPlan>;
+export {};
+//# sourceMappingURL=revoke.d.ts.map