@openlfcp/client 0.1.4 → 0.2.0-beta.1

package/dist/typing.d.ts

@@ -0,0 +1,60 @@
+import type { Receipt } from "./receipts.js";
+/** What submit did with a pass. */
+export type Submitted = 
+/** Committed now: its receipt. */
+{
+    readonly kind: "committed";
+    readonly receipt: Receipt;
+    readonly replaced: string | null;
+}
+/** Waiting for more typing; `replaced` is the waiting pass it replaces, which is dropped. */
+ | {
+    readonly kind: "deferred";
+    readonly operationId: string;
+    readonly replaced: string | null;
+};
+/** A waiting pass committed by tick() or flush(), or its failure. */
+export type Flushed = {
+    readonly kind: "committed";
+    readonly key: string;
+    readonly operationId: string;
+    readonly receipt: Receipt;
+} | {
+    readonly kind: "failed";
+    readonly key: string;
+    readonly operationId: string;
+    readonly intents: readonly unknown[];
+    readonly error: unknown;
+};
+export interface TypingCoalescerOptions {
+    /** The durable commit (SyncClient.commit for the projection's Resource). */
+    commit(intents: readonly unknown[], options: {
+        readonly operationId: string;
+    }): Promise<Receipt>;
+    /** A waiting pass was committed or failed outside submit (tick, flush). */
+    onFlushed?(flushed: Flushed): void;
+    /** Idle pause after which a waiting pass is committed (ms, default 1,500). */
+    readonly idleMs?: number;
+    /** Characters inserted or deleted after which a pass is committed (default 256). */
+    readonly maxChars?: number;
+    /** The local clock (ms), for the idle pause. */
+    now(): number;
+}
+export declare class TypingCoalescer {
+    #private;
+    constructor(options: TypingCoalescerOptions);
+    /**
+     * Commits `intents` now or lets them wait for more typing (see above).
+     * `key` names the projection whose base the pass was planned on.
+     */
+    submit(key: string, intents: readonly unknown[], options: {
+        readonly operationId: string;
+    }): Promise<Submitted>;
+    /** Commits every pass that waited `idleMs` or longer at `now`, reporting each through onFlushed. */
+    tick(now: number): Promise<void>;
+    /** Commits the waiting pass of `key` (every key without one), reporting each through onFlushed. */
+    flush(key?: string): Promise<void>;
+    /** The operation ID of the pass waiting for `key`, if any. */
+    waiting(key: string): string | undefined;
+}
+//# sourceMappingURL=typing.d.ts.map

package/dist/typing.js

@@ -0,0 +1,110 @@
+const isTextEdit = (i) => typeof i === "object" &&
+    i !== null &&
+    i.intent === "text.edit" &&
+    typeof i.id === "string" &&
+    typeof i.base === "string" &&
+    Array.isArray(i.edits);
+export class TypingCoalescer {
+    #o;
+    #idleMs;
+    #maxChars;
+    /** The waiting pass per key (a projection). */
+    #waiting = new Map();
+    /** Serializes commits per key. */
+    #chain = new Map();
+    constructor(options) {
+        this.#o = options;
+        this.#idleMs = options.idleMs ?? 1_500;
+        this.#maxChars = options.maxChars ?? 256;
+    }
+    /**
+     * Commits `intents` now or lets them wait for more typing (see above).
+     * `key` names the projection whose base the pass was planned on.
+     */
+    submit(key, intents, options) {
+        return this.#serial(key, async () => {
+            const waiting = this.#waiting.get(key);
+            const textOnly = intents.length > 0 && intents.every(isTextEdit);
+            const edits = intents.filter(isTextEdit);
+            const bases = new Map(edits.map((e) => [e.id, e.base]));
+            // A later pass on the same base contains the waiting one and replaces
+            // it. A node edited on another base means the base moved without a
+            // flush: the waiting pass is not contained, so it is committed first.
+            let replaced = null;
+            if (waiting !== undefined) {
+                const sameBase = [...bases].every(([id, base]) => !waiting.bases.has(id) || waiting.bases.get(id) === base);
+                this.#drop(key);
+                if (sameBase)
+                    replaced = waiting.operationId;
+                else
+                    await this.#commitWaiting(key, waiting, false);
+            }
+            const chars = edits.reduce((n, e) => n + e.edits.reduce((m, x) => m + x.insert.length + x.deleteCount, 0), 0);
+            // The burst moved to another paragraph: the pass ends it.
+            const leftNode = waiting !== undefined &&
+                replaced !== null &&
+                [...bases.keys()].some((n) => !waiting.bases.has(n));
+            if (!textOnly || chars >= this.#maxChars || leftNode) {
+                const receipt = await this.#o.commit(intents, options);
+                return { kind: "committed", receipt, replaced };
+            }
+            const w = { operationId: options.operationId, intents, bases, at: this.#o.now() };
+            this.#waiting.set(key, w);
+            return { kind: "deferred", operationId: options.operationId, replaced };
+        });
+    }
+    /** Commits every pass that waited `idleMs` or longer at `now`, reporting each through onFlushed. */
+    async tick(now) {
+        for (const [key, w] of [...this.#waiting])
+            if (now - w.at >= this.#idleMs)
+                await this.#serial(key, async () => {
+                    if (this.#waiting.get(key) !== w)
+                        return;
+                    this.#waiting.delete(key);
+                    await this.#commitWaiting(key, w, true);
+                });
+    }
+    /** Commits the waiting pass of `key` (every key without one), reporting each through onFlushed. */
+    async flush(key) {
+        const keys = key === undefined ? [...this.#waiting.keys()] : [key];
+        for (const k of keys)
+            await this.#serial(k, async () => {
+                const w = this.#waiting.get(k);
+                if (w === undefined)
+                    return;
+                this.#drop(k);
+                await this.#commitWaiting(k, w, true);
+            });
+    }
+    /** The operation ID of the pass waiting for `key`, if any. */
+    waiting(key) {
+        return this.#waiting.get(key)?.operationId;
+    }
+    #drop(key) {
+        this.#waiting.delete(key);
+    }
+    /** Commits a waiting pass; `report` sends the outcome to onFlushed, else a failure throws. */
+    async #commitWaiting(key, w, report) {
+        try {
+            const receipt = await this.#o.commit(w.intents, { operationId: w.operationId });
+            this.#o.onFlushed?.({ kind: "committed", key, operationId: w.operationId, receipt });
+        }
+        catch (error) {
+            this.#o.onFlushed?.({
+                kind: "failed",
+                key,
+                operationId: w.operationId,
+                intents: w.intents,
+                error,
+            });
+            if (!report)
+                throw error;
+        }
+    }
+    #serial(key, fn) {
+        const run = (this.#chain.get(key) ?? Promise.resolve()).then(fn, fn);
+        this.#chain.set(key, run.catch(() => undefined));
+        return run;
+    }
+}
+//# sourceMappingURL=typing.js.map

package/dist/write-access.d.ts

@@ -0,0 +1,115 @@
+import { type ControlRecordId, type PrincipalId } from "@openlfcp/core";
+import { type ChainResult, type ControlBody } from "@openlfcp/wire";
+/**
+ * Write access (SDK-SECTIONS-INTEGRATION-01 §6): whether this client may
+ * commit to a Resource, decided from the validated Control state only.
+ */
+/** §6: why writing is not allowed. */
+export type WriteDeniedReason = "not-member" | "read-only" | "key-unavailable" | "revoked" | "unknown"
+/**
+ * LFCP-02-115: the server refuses this client the Resource
+ * (AUTHORIZATION_FAILED on RESOURCE_OPEN) although the local chain grants
+ * it. The server does not say why: a revocation this client has not seen,
+ * or a server that lost state and could not be recovered (106).
+ */
+ | "server-refused";
+/** §6: the answer of canWrite. `controlHead` and `verifiedAt` are its freshness. */
+export interface WriteAccess {
+    readonly allowed: boolean;
+    /** Why not, when not allowed; null when allowed. */
+    readonly reason: WriteDeniedReason | null;
+    /** The Control Head the decision was validated at; null without a validated chain. */
+    readonly controlHead: ControlRecordId | null;
+    /** The local time (ms since the epoch) of that validation; null without one. */
+    readonly verifiedAt: number | null;
+}
+/** §3.6: a batch submitted while writing is not allowed. A local SDK error; nothing is written. */
+export declare class NotWritableError extends Error {
+    readonly access: WriteAccess;
+    readonly code = "NOT_WRITABLE";
+    constructor(access: WriteAccess);
+}
+/** The answer without a validated chain: unknown, never a default (§2). */
+export declare const UNKNOWN_ACCESS: WriteAccess;
+/**
+ * Decides write access for `principal` from a validated chain: `data/write`
+ * (LFCP-WIRE-01 §17) and the current epoch's DEK are both needed. Without
+ * `data/write`, a principal holding `data/read` is read-only, one whose
+ * every grant is inactive (revoked, or delegated from a revoked one, §17.2)
+ * is revoked, and anyone else is not a member.
+ */
+export declare function writeAccess(chain: ChainResult | undefined | null, principal: PrincipalId, hasCurrentDek: boolean, verifiedAt: number): WriteAccess;
+/** One grant path to this principal (§17.2): an active grant naming it. */
+export interface GrantPath {
+    readonly grantId: ControlRecordId;
+    readonly source: "grant" | "claim";
+    /** The ability names it lists. */
+    readonly abilities: readonly string[];
+    /** It is delegated from another grant (§17.2): active while that one is. */
+    readonly delegated: boolean;
+}
+/** An invitation this principal issued (§18.1): not access of anyone until claimed. */
+export interface IssuedInvitation {
+    readonly grantId: ControlRecordId;
+    readonly claimLimit: bigint;
+    readonly claimsUsed: bigint;
+}
+/** A Control Record of this principal sent and not committed yet (SI14): pending, never done. */
+export interface PendingControl {
+    readonly recordId: ControlRecordId;
+    readonly type: ControlBody["type"];
+}
+/**
+ * LFCP-02-027: write access with the evidence around it. `abilities` and
+ * `paths` are active access at `controlHead`; invitations issued, our own
+ * pending Control Records and an unsettled invitation claim are kept
+ * apart and never count as access.
+ */
+export interface AccessState extends WriteAccess {
+    /** The Control sequence of `controlHead`; null without a validated chain. */
+    readonly controlSeq: bigint | null;
+    /** The highest Control sequence a server reported in this session; null when none did. */
+    readonly serverControlSeq: bigint | null;
+    /**
+     * Whether the validated chain reaches what the server reported: false
+     * while it is behind (a stale Control view: the access may already have
+     * changed), null when no server reported a head in this session.
+     */
+    readonly current: boolean | null;
+    readonly owner: boolean;
+    /** Effective ability names (§17.1), over every active grant path. */
+    readonly abilities: readonly string[];
+    readonly paths: readonly GrantPath[];
+    readonly invitations: readonly IssuedInvitation[];
+    readonly pendingControl: readonly PendingControl[];
+    /** An invitation claim of this principal is journaled and not settled (LFCP-02-110). */
+    readonly pendingClaim: boolean;
+    /**
+     * LFCP-02-115: the server refuses this client the Resource in this
+     * session; then `allowed` is false with reason "server-refused" and
+     * `current` is false, whatever the local chain says.
+     */
+    readonly serverRefusal: ServerRefusal | null;
+}
+/** LFCP-02-115: the server's refusal of the Resource in this session, as far as it is known. */
+export interface ServerRefusal {
+    /** The §62 code, AUTHORIZATION_FAILED. */
+    readonly code: string;
+    /**
+     * How the access recovery (LFCP-02-106) ended, when it ran: "unknown-head"
+     * (the server holds Control Records this client has not seen), "refused",
+     * "still-refused", "not-granted", "server-current"; null when it did not run.
+     */
+    readonly recovery: string | null;
+}
+/** The evidence of `accessState` the chain does not hold. */
+export interface AccessContext {
+    /** The server refuses the Resource in this session (LFCP-02-115). */
+    readonly serverRefusal?: ServerRefusal | null;
+    readonly serverControlSeq: bigint | null;
+    readonly pendingControl: readonly PendingControl[];
+    readonly pendingClaim: boolean;
+}
+/** AccessState from a validated chain (see writeAccess) and the context around it. */
+export declare function accessState(chain: ChainResult | undefined | null, principal: PrincipalId, hasCurrentDek: boolean, verifiedAt: number, context: AccessContext): AccessState;
+//# sourceMappingURL=write-access.d.ts.map

package/dist/write-access.js

@@ -0,0 +1,87 @@
+import { bytesEqual } from "@openlfcp/core";
+import { ABILITY, ABILITY_NAMES, abilitiesOf, hasAbility, isGrantActive, } from "@openlfcp/wire";
+/** §3.6: a batch submitted while writing is not allowed. A local SDK error; nothing is written. */
+export class NotWritableError extends Error {
+    access;
+    code = "NOT_WRITABLE";
+    constructor(access) {
+        super(`writing is not allowed: ${access.reason ?? "unknown"} (SDK-SECTIONS-INTEGRATION-01 §6)`);
+        this.access = access;
+        this.name = "NotWritableError";
+    }
+}
+/** The answer without a validated chain: unknown, never a default (§2). */
+export const UNKNOWN_ACCESS = Object.freeze({
+    allowed: false,
+    reason: "unknown",
+    controlHead: null,
+    verifiedAt: null,
+});
+/**
+ * Decides write access for `principal` from a validated chain: `data/write`
+ * (LFCP-WIRE-01 §17) and the current epoch's DEK are both needed. Without
+ * `data/write`, a principal holding `data/read` is read-only, one whose
+ * every grant is inactive (revoked, or delegated from a revoked one, §17.2)
+ * is revoked, and anyone else is not a member.
+ */
+export function writeAccess(chain, principal, hasCurrentDek, verifiedAt) {
+    if (chain?.kind !== "linear")
+        return UNKNOWN_ACCESS;
+    const { state } = chain;
+    const at = { controlHead: state.head, verifiedAt };
+    const denied = (reason) => Object.freeze({ allowed: false, reason, ...at });
+    if (!hasAbility(state, principal, ABILITY.DATA_WRITE)) {
+        if (hasAbility(state, principal, ABILITY.DATA_READ))
+            return denied("read-only");
+        const grants = [...state.grants.values()].filter((g) => bytesEqual(g.subject, principal));
+        return denied(grants.some((g) => !isGrantActive(state, g.id)) ? "revoked" : "not-member");
+    }
+    if (!hasCurrentDek)
+        return denied("key-unavailable");
+    return Object.freeze({ allowed: true, reason: null, ...at });
+}
+/** AccessState from a validated chain (see writeAccess) and the context around it. */
+export function accessState(chain, principal, hasCurrentDek, verifiedAt, context) {
+    const write = writeAccess(chain, principal, hasCurrentDek, verifiedAt);
+    const state = chain?.kind === "linear" ? chain.state : undefined;
+    const controlSeq = state?.seq ?? null;
+    const server = context.serverControlSeq;
+    const name = (a) => ABILITY_NAMES.get(a) ?? `${a}`;
+    const grants = state === undefined ? [] : [...state.grants.values()];
+    const refusal = context.serverRefusal ?? null;
+    return Object.freeze({
+        ...write,
+        ...(refusal === null ? {} : { allowed: false, reason: "server-refused" }),
+        controlSeq,
+        serverControlSeq: server,
+        current: refusal !== null
+            ? false
+            : server === null || controlSeq === null
+                ? null
+                : controlSeq >= server,
+        owner: state !== undefined && bytesEqual(state.owner.principalId, principal),
+        abilities: Object.freeze(state === undefined ? [] : abilitiesOf(state, principal).map(name)),
+        paths: Object.freeze(grants
+            .filter((g) => state !== undefined && bytesEqual(g.subject, principal) && isGrantActive(state, g.id))
+            .map((g) => Object.freeze({
+            grantId: g.id,
+            source: g.source,
+            abilities: Object.freeze(g.abilities.map(name)),
+            delegated: g.parentGrantId !== null,
+        }))),
+        invitations: Object.freeze(grants
+            .filter((g) => state !== undefined &&
+            g.claimLimit !== null &&
+            bytesEqual(g.issuer, principal) &&
+            isGrantActive(state, g.id))
+            .map((g) => Object.freeze({
+            grantId: g.id,
+            claimLimit: g.claimLimit,
+            claimsUsed: g.claimsUsed,
+        }))),
+        pendingControl: Object.freeze([...context.pendingControl]),
+        pendingClaim: context.pendingClaim,
+        serverRefusal: refusal === null ? null : Object.freeze({ ...refusal }),
+    });
+}
+//# sourceMappingURL=write-access.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/client",
-  "version": "0.1.4",
+  "version": "0.2.0-beta.1",
   "description": "LFCP client: session, Control Plane and Data Plane synchronization.",
   "keywords": [
     "openlfcp",
@@ -39,12 +39,12 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "latest"
+    "tag": "beta"
   },
   "dependencies": {
-    "@openlfcp/core": "^0.1.4",
-    "@openlfcp/crypto": "^0.1.4",
-    "@openlfcp/wire": "^0.1.4",
-    "@openlfcp/storage": "^0.1.4"
+    "@openlfcp/core": "^0.2.0-beta.1",
+    "@openlfcp/crypto": "^0.2.0-beta.1",
+    "@openlfcp/storage": "^0.2.0-beta.1",
+    "@openlfcp/wire": "^0.2.0-beta.1"
   }
 }