@floegence/flowersec-core 0.27.0 → 2.0.0

package/dist/proxy/wsPatch.js

@@ -1,113 +1,88 @@
-import { createByteReader } from "../streamio/index.js";
 import { readU32be, u16be, u32be } from "../utils/bin.js";
-import { DEFAULT_MAX_WS_FRAME_BYTES } from "./constants.js";
-function readU16be(buf, off) {
-    return ((buf[off] << 8) | buf[off + 1]) >>> 0;
-}
-const te = new TextEncoder();
-const td = new TextDecoder();
-function defaultPortForProtocol(protocol) {
-    // Protocol strings include the trailing ':' in URL (e.g. 'http:', 'ws:').
+import { ProxyByteReader, writeAll } from "./stream.js";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function defaultPort(protocol) {
     if (protocol === "http:" || protocol === "ws:")
         return "80";
     if (protocol === "https:" || protocol === "wss:")
         return "443";
     return "";
 }
-class ListenerMap {
-    map = new Map();
-    on(type, cb) {
-        let s = this.map.get(type);
-        if (!s) {
-            s = new Set();
-            this.map.set(type, s);
-        }
-        s.add(cb);
-    }
-    off(type, cb) {
-        this.map.get(type)?.delete(cb);
+function readU16(input) {
+    return ((input[0] << 8) | input[1]) >>> 0;
+}
+async function writeFrame(stream, opcode, payload, maximum) {
+    if (payload.length > maximum)
+        throw new Error("WebSocket frame exceeds the proxy limit");
+    const header = new Uint8Array(5);
+    header[0] = opcode;
+    header.set(u32be(payload.length), 1);
+    await writeAll(stream, header);
+    await writeAll(stream, payload);
+}
+async function readFrame(reader, maximum) {
+    const header = await reader.readExactly(5);
+    const length = readU32be(header, 1);
+    if (length > maximum)
+        throw new Error("WebSocket frame exceeds the proxy limit");
+    return { opcode: header[0], payload: await reader.readExactly(length) };
+}
+class EventListeners {
+    values = new Map();
+    add(type, listener) {
+        const entries = this.values.get(type) ?? new Set();
+        entries.add(listener);
+        this.values.set(type, entries);
     }
-    emit(type, ev) {
-        for (const cb of this.map.get(type) ?? []) {
+    remove(type, listener) { this.values.get(type)?.delete(listener); }
+    dispatch(type, event, target) {
+        for (const listener of this.values.get(type) ?? []) {
             try {
-                cb.call(null, ev);
+                if (typeof listener === "function")
+                    listener.call(target, event);
+                else
+                    listener.handleEvent(event);
             }
             catch {
-                // Best-effort event fanout.
+                // Event listener failures do not corrupt the transport state.
             }
         }
     }
 }
-async function writeWSFrame(stream, op, payload, maxPayload) {
-    if (maxPayload > 0 && payload.length > maxPayload)
-        throw new Error("ws payload too large");
-    const hdr = new Uint8Array(5);
-    hdr[0] = op & 0xff;
-    hdr.set(u32be(payload.length), 1);
-    await stream.write(hdr);
-    if (payload.length > 0)
-        await stream.write(payload);
+function limit(name, input, fallback) {
+    const value = input ?? fallback;
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new TypeError(`${name} must be a positive safe integer`);
+    return value;
 }
-async function readWSFrame(reader, maxPayload) {
-    const hdr = await reader.readExactly(5);
-    const op = hdr[0];
-    const n = readU32be(hdr, 1);
-    if (maxPayload > 0 && n > maxPayload)
-        throw new Error("ws payload too large");
-    const payload = n === 0 ? new Uint8Array() : await reader.readExactly(n);
-    return { op, payload };
-}
-export function installWebSocketPatch(opts) {
+export function installWebSocketPatch(options) {
     const Original = globalThis.WebSocket;
-    if (Original == null) {
-        return { uninstall: () => { } };
-    }
-    const shouldProxy = opts.shouldProxy ??
-        ((u) => {
-            const loc = globalThis.location;
-            const hostname = typeof loc?.hostname === "string" ? loc.hostname : "";
-            if (hostname === "")
-                return false;
-            const locProto = typeof loc?.protocol === "string" ? loc.protocol : "";
-            const locPortRaw = typeof loc?.port === "string" ? loc.port : "";
-            const locPort = locPortRaw !== "" ? locPortRaw : defaultPortForProtocol(locProto);
-            const uPort = u.port !== "" ? u.port : defaultPortForProtocol(u.protocol);
-            return u.hostname === hostname && uPort === locPort;
-        });
-    const runtime = opts.runtime;
-    const runtimeMaxWsFrameBytes = typeof runtime.limits?.maxWsFrameBytes === "number" && Number.isFinite(runtime.limits.maxWsFrameBytes)
-        ? runtime.limits.maxWsFrameBytes
-        : DEFAULT_MAX_WS_FRAME_BYTES;
-    const maxWsFrameBytesRaw = opts.maxWsFrameBytes ?? runtimeMaxWsFrameBytes;
-    if (!Number.isFinite(maxWsFrameBytesRaw))
-        throw new Error("maxWsFrameBytes must be a finite number");
-    const maxWsFrameBytesFloor = Math.floor(maxWsFrameBytesRaw);
-    if (maxWsFrameBytesFloor < 0)
-        throw new Error("maxWsFrameBytes must be >= 0");
-    const maxWsFrameBytes = maxWsFrameBytesFloor === 0 ? runtimeMaxWsFrameBytes : maxWsFrameBytesFloor;
-    const defaultMaxWsBufferedAmountBytes = 4 * (1 << 20);
-    const runtimeMaxWsBufferedAmountBytesRaw = runtime.limits?.maxWsBufferedAmountBytes;
-    if (runtimeMaxWsBufferedAmountBytesRaw !== undefined &&
-        (!Number.isSafeInteger(runtimeMaxWsBufferedAmountBytesRaw) || runtimeMaxWsBufferedAmountBytesRaw < 0)) {
-        throw new Error("runtime maxWsBufferedAmountBytes must be a non-negative safe integer");
-    }
-    const runtimeMaxWsBufferedAmountBytes = runtimeMaxWsBufferedAmountBytesRaw == null || runtimeMaxWsBufferedAmountBytesRaw === 0
-        ? defaultMaxWsBufferedAmountBytes
-        : runtimeMaxWsBufferedAmountBytesRaw;
-    const maxWsBufferedAmountBytesRaw = opts.maxWsBufferedAmountBytes ?? runtimeMaxWsBufferedAmountBytes;
-    if (!Number.isSafeInteger(maxWsBufferedAmountBytesRaw) || maxWsBufferedAmountBytesRaw < 0) {
-        throw new Error("maxWsBufferedAmountBytes must be a non-negative safe integer");
-    }
-    const maxWsBufferedAmountBytes = maxWsBufferedAmountBytesRaw === 0
-        ? runtimeMaxWsBufferedAmountBytes
-        : maxWsBufferedAmountBytesRaw;
-    class PatchedWebSocket {
+    if (Original === undefined)
+        return Object.freeze({ uninstall: () => undefined });
+    const NativeWebSocket = Original;
+    const runtimeLimits = options.runtime.limits;
+    const maxFrameBytes = limit("maxWsFrameBytes", options.maxWsFrameBytes, runtimeLimits.maxWsFrameBytes ?? 1024 * 1024);
+    const maxBufferedBytes = limit("maxWsBufferedAmountBytes", options.maxWsBufferedAmountBytes, runtimeLimits.maxWsBufferedAmountBytes ?? 4 * 1024 * 1024);
+    const shouldProxy = options.shouldProxy ?? ((url) => {
+        const location = globalThis.location;
+        if (location?.hostname === undefined || location.hostname === "")
+            return false;
+        const localPort = location.port || defaultPort(location.protocol);
+        const remotePort = url.port || defaultPort(url.protocol);
+        return url.hostname === location.hostname && remotePort === localPort;
+    });
+    class ProxyWebSocket {
         static CONNECTING = 0;
         static OPEN = 1;
         static CLOSING = 2;
         static CLOSED = 3;
+        CONNECTING = 0;
+        OPEN = 1;
+        CLOSING = 2;
+        CLOSED = 3;
         url = "";
-        readyState = PatchedWebSocket.CONNECTING;
+        readyState = ProxyWebSocket.CONNECTING;
         bufferedAmount = 0;
         extensions = "";
         protocol = "";
@@ -116,206 +91,136 @@ export function installWebSocketPatch(opts) {
         onmessage = null;
         onerror = null;
         onclose = null;
-        listeners = new ListenerMap();
-        ac = new AbortController();
-        stream = null;
-        readLoopPromise = null;
-        writeChain = Promise.resolve();
-        constructor(url, protocols) {
-            const u = new URL(String(url), globalThis.location?.href);
-            if (!shouldProxy(u)) {
-                return new Original(String(url), protocols);
-            }
-            this.url = u.toString();
-            void this.init(u, protocols);
-        }
-        addEventListener(type, listener) {
-            this.listeners.on(type, listener);
-        }
-        removeEventListener(type, listener) {
-            this.listeners.off(type, listener);
-        }
-        queueWriteFrame(stream, op, payload, bufferedBytes = 0) {
-            this.writeChain = this.writeChain
-                .then(async () => {
-                if (this.readyState === PatchedWebSocket.CLOSED)
-                    return;
-                const resolved = typeof payload === "function" ? await payload() : payload;
-                await writeWSFrame(stream, op, resolved, maxWsFrameBytes);
-            })
-                .catch((e) => this.fail(e))
-                .finally(() => {
-                this.bufferedAmount = Math.max(0, this.bufferedAmount - bufferedBytes);
-            });
-        }
-        reserveBufferedAmount(bytes) {
-            if (this.bufferedAmount + bytes > maxWsBufferedAmountBytes) {
-                this.fail(new Error("WebSocket bufferedAmount limit exceeded"));
-                return false;
-            }
-            this.bufferedAmount += bytes;
-            return true;
+        listeners = new EventListeners();
+        abort = new AbortController();
+        stream;
+        writes = Promise.resolve();
+        constructor(input, protocols) {
+            const url = new URL(String(input), globalThis.location?.href);
+            if (!shouldProxy(url))
+                return new NativeWebSocket(input, protocols);
+            this.url = url.toString();
+            void this.connect(url, protocols);
         }
+        addEventListener(type, listener) { this.listeners.add(type, listener); }
+        removeEventListener(type, listener) { this.listeners.remove(type, listener); }
+        dispatchEvent(event) { this.listeners.dispatch(event.type, event, this); return !event.defaultPrevented; }
         send(data) {
-            if (this.readyState !== PatchedWebSocket.OPEN || this.stream == null) {
-                throw new Error("WebSocket is not open");
-            }
-            const s = this.stream;
-            const sendBytes = (op, byteLength, copyPayload) => {
-                if (!this.reserveBufferedAmount(byteLength))
-                    return;
-                try {
-                    this.queueWriteFrame(s, op, copyPayload(), byteLength);
-                }
-                catch (error) {
-                    this.bufferedAmount = Math.max(0, this.bufferedAmount - byteLength);
-                    throw error;
-                }
-            };
+            if (this.readyState !== ProxyWebSocket.OPEN || this.stream === undefined)
+                throw new DOMException("WebSocket is not open", "InvalidStateError");
+            let opcode;
+            let bytes;
+            let load;
             if (typeof data === "string") {
-                const payload = te.encode(data);
-                sendBytes(1, payload.byteLength, () => payload);
-                return;
-            }
-            if (data instanceof ArrayBuffer) {
-                sendBytes(2, data.byteLength, () => new Uint8Array(data).slice());
+                const encoded = encoder.encode(data);
+                opcode = 1;
+                bytes = encoded.length;
+                load = async () => encoded;
+            }
+            else if (typeof Blob !== "undefined" && data instanceof Blob) {
+                opcode = 2;
+                bytes = data.size;
+                load = async () => new Uint8Array(await data.arrayBuffer());
+            }
+            else if (ArrayBuffer.isView(data)) {
+                opcode = 2;
+                bytes = data.byteLength;
+                load = async () => new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+            }
+            else {
+                const buffer = data;
+                opcode = 2;
+                bytes = buffer.byteLength;
+                load = async () => new Uint8Array(buffer).slice();
+            }
+            if (bytes > maxFrameBytes || this.bufferedAmount + bytes > maxBufferedBytes) {
+                this.fail();
                 return;
             }
-            if (ArrayBuffer.isView(data)) {
-                sendBytes(2, data.byteLength, () => new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice());
+            this.bufferedAmount += bytes;
+            const stream = this.stream;
+            this.writes = this.writes.then(async () => await writeFrame(stream, opcode, await load(), maxFrameBytes))
+                .catch(() => this.fail())
+                .finally(() => { this.bufferedAmount = Math.max(0, this.bufferedAmount - bytes); });
+        }
+        close(code, reason = "") {
+            if (this.readyState === ProxyWebSocket.CLOSED || this.readyState === ProxyWebSocket.CLOSING)
                 return;
+            if (code !== undefined && (code < 1000 || code > 4999 || code === 1005 || code === 1006 || code === 1015)) {
+                throw new DOMException("Invalid WebSocket close code", "InvalidAccessError");
+            }
+            const reasonBytes = encoder.encode(reason);
+            if (reasonBytes.length > 123)
+                throw new DOMException("WebSocket close reason is too long", "SyntaxError");
+            this.readyState = ProxyWebSocket.CLOSING;
+            const payload = code === undefined ? new Uint8Array() : new Uint8Array([...u16be(code), ...reasonBytes]);
+            this.writes = this.writes.then(async () => {
+                if (this.stream !== undefined)
+                    await writeFrame(this.stream, 8, payload, maxFrameBytes);
+            }).catch(() => undefined).finally(() => this.abort.abort());
+        }
+        async connect(url, protocols) {
+            try {
+                const opened = await options.runtime.openWebSocketStream(url.pathname + url.search, {
+                    protocols: typeof protocols === "string" ? [protocols] : protocols ?? [],
+                    signal: this.abort.signal,
+                });
+                this.stream = opened.stream;
+                this.protocol = opened.protocol;
+                this.readyState = ProxyWebSocket.OPEN;
+                this.emit("open", new Event("open"));
+                await this.readLoop(opened.stream);
             }
-            if (typeof Blob !== "undefined" && data instanceof Blob) {
-                if (!this.reserveBufferedAmount(data.size))
-                    return;
-                this.queueWriteFrame(s, 2, async () => new Uint8Array(await data.arrayBuffer()), data.size);
-                return;
+            catch {
+                this.fail();
             }
-            throw new Error("unsupported WebSocket send payload");
         }
-        close(code, reason) {
-            if (this.readyState === PatchedWebSocket.CLOSED)
-                return;
-            this.readyState = PatchedWebSocket.CLOSING;
-            const payloadParts = [];
-            if (code != null)
-                payloadParts.push(u16be(code));
-            if (reason != null && reason !== "")
-                payloadParts.push(te.encode(reason));
-            const payload = payloadParts.length === 0 ? new Uint8Array() : payloadParts.reduce((a, b) => {
-                const out = new Uint8Array(a.length + b.length);
-                out.set(a, 0);
-                out.set(b, a.length);
-                return out;
-            });
-            this.writeChain = this.writeChain
-                .then(() => (this.stream ? writeWSFrame(this.stream, 8, payload, maxWsFrameBytes) : undefined))
-                .catch(() => undefined)
-                .finally(() => {
-                try {
-                    this.ac.abort("closed");
+        async readLoop(stream) {
+            const reader = new ProxyByteReader(stream, { signal: this.abort.signal });
+            while (this.readyState !== ProxyWebSocket.CLOSED) {
+                const frame = await readFrame(reader, maxFrameBytes);
+                if (frame.opcode === 9) {
+                    this.writes = this.writes.then(async () => await writeFrame(stream, 10, frame.payload, maxFrameBytes)).catch(() => this.fail());
                 }
-                catch {
-                    // Best-effort abort.
+                else if (frame.opcode === 8) {
+                    const code = frame.payload.length >= 2 ? readU16(frame.payload) : 1000;
+                    const reason = frame.payload.length > 2 ? decoder.decode(frame.payload.subarray(2)) : "";
+                    this.readyState = ProxyWebSocket.CLOSED;
+                    this.emit("close", new CloseEvent("close", { code, reason, wasClean: true }));
+                    return;
                 }
-            });
-        }
-        emit(type, ev) {
-            const prop = this["on" + type];
-            if (typeof prop === "function") {
-                try {
-                    prop.call(this, ev);
+                else if (frame.opcode === 1) {
+                    this.emit("message", new MessageEvent("message", { data: decoder.decode(frame.payload) }));
                 }
-                catch {
-                    // Best-effort.
+                else if (frame.opcode === 2) {
+                    const data = this.binaryType === "arraybuffer"
+                        ? frame.payload.slice().buffer
+                        : new Blob([frame.payload.slice()]);
+                    this.emit("message", new MessageEvent("message", { data }));
                 }
             }
-            this.listeners.emit(type, ev);
         }
-        async init(u, protocols) {
+        emit(type, event) {
+            const callback = this[`on${type}`];
             try {
-                const list = typeof protocols === "string"
-                    ? [protocols]
-                    : Array.isArray(protocols)
-                        ? protocols
-                        : [];
-                const { stream, protocol } = await runtime.openWebSocketStream(u.pathname + u.search, {
-                    protocols: list,
-                    signal: this.ac.signal
-                });
-                this.stream = stream;
-                this.protocol = protocol;
-                this.readyState = PatchedWebSocket.OPEN;
-                this.emit("open", { type: "open" });
-                this.readLoopPromise = this.readLoop(stream, this.ac.signal);
-            }
-            catch (e) {
-                this.fail(e);
+                callback?.call(this, event);
             }
+            catch { /* User event handlers are isolated. */ }
+            this.listeners.dispatch(type, event, this);
         }
-        async readLoop(stream, signal) {
-            const reader = createByteReader(stream, { signal });
-            try {
-                while (true) {
-                    const { op, payload } = await readWSFrame(reader, maxWsFrameBytes);
-                    if (op === 9) {
-                        // Ping -> Pong (not exposed to WebSocket JS API).
-                        // Must be serialized with user writes, otherwise concurrent writes can corrupt framing.
-                        this.queueWriteFrame(stream, 10, payload);
-                        continue;
-                    }
-                    if (op === 10)
-                        continue;
-                    if (op === 8) {
-                        this.readyState = PatchedWebSocket.CLOSED;
-                        const code = payload.length >= 2 ? readU16be(payload, 0) : 1000;
-                        const reason = payload.length > 2 ? td.decode(payload.subarray(2)) : "";
-                        this.emit("close", { type: "close", code, reason, wasClean: true });
-                        return;
-                    }
-                    if (op === 1) {
-                        this.emit("message", { type: "message", data: td.decode(payload) });
-                        continue;
-                    }
-                    if (op === 2) {
-                        if (this.binaryType === "arraybuffer") {
-                            const ab = payload.buffer.slice(payload.byteOffset, payload.byteOffset + payload.byteLength);
-                            this.emit("message", { type: "message", data: ab });
-                            continue;
-                        }
-                        if (typeof Blob !== "undefined") {
-                            this.emit("message", { type: "message", data: new Blob([new Uint8Array(payload)]) });
-                            continue;
-                        }
-                        // Fallback for non-browser contexts.
-                        const ab = payload.buffer.slice(payload.byteOffset, payload.byteOffset + payload.byteLength);
-                        this.emit("message", { type: "message", data: ab });
-                        continue;
-                    }
-                }
-            }
-            catch (e) {
-                if (this.readyState !== PatchedWebSocket.CLOSED)
-                    this.fail(e);
-            }
-        }
-        fail(e) {
-            if (this.readyState === PatchedWebSocket.CLOSED)
+        fail() {
+            if (this.readyState === ProxyWebSocket.CLOSED)
                 return;
-            this.readyState = PatchedWebSocket.CLOSED;
-            const msg = e instanceof Error ? e.message : String(e);
+            this.readyState = ProxyWebSocket.CLOSED;
             this.bufferedAmount = 0;
-            this.emit("error", { type: "error", message: msg });
-            this.emit("close", { type: "close", code: 1006, reason: msg, wasClean: false });
-            this.stream = null;
-            try {
-                this.ac.abort(msg);
-            }
-            catch {
-                // Best-effort.
-            }
+            this.emit("error", new Event("error"));
+            this.emit("close", new CloseEvent("close", { code: 1006, reason: "proxy WebSocket failed", wasClean: false }));
+            this.stream = undefined;
+            this.abort.abort();
         }
     }
-    globalThis.WebSocket = PatchedWebSocket;
-    return { uninstall: () => (globalThis.WebSocket = Original) };
+    globalThis.WebSocket = ProxyWebSocket;
+    return Object.freeze({
+        uninstall: () => { globalThis.WebSocket = NativeWebSocket; },
+    });
 }

package/dist/public/artifact.d.ts

@@ -0,0 +1,11 @@
+export declare class Artifact {
+    private readonly artifactBrand;
+    private constructor();
+}
+export type ArtifactErrorCode = "artifact_too_large" | "invalid_artifact" | "invalid_candidate";
+/** A stable, redacted failure returned while parsing an opaque artifact. */
+export declare class ArtifactError extends Error {
+    readonly code: ArtifactErrorCode;
+    constructor(code: ArtifactErrorCode);
+}
+export declare function parseArtifact(input: string | Uint8Array): Artifact;

package/dist/public/artifact.js

@@ -0,0 +1,44 @@
+import { ArtifactV2Error, decodeArtifactV2JSON } from "../v2/artifact.js";
+const artifactValues = new WeakMap();
+export class Artifact {
+    constructor() { }
+}
+/** A stable, redacted failure returned while parsing an opaque artifact. */
+export class ArtifactError extends Error {
+    code;
+    constructor(code) {
+        super(`Flowersec artifact parsing failed (code=${code})`);
+        this.code = code;
+        this.name = "ArtifactError";
+    }
+}
+export function parseArtifact(input) {
+    try {
+        return wrapArtifact(decodeArtifactV2JSON(input));
+    }
+    catch (error) {
+        if (error instanceof ArtifactV2Error) {
+            switch (error.code) {
+                case "artifact_too_large":
+                case "invalid_candidate":
+                    throw new ArtifactError(error.code);
+                default:
+                    throw new ArtifactError("invalid_artifact");
+            }
+        }
+        throw new ArtifactError("invalid_artifact");
+    }
+}
+/** @internal */
+export function wrapArtifact(value) {
+    const artifact = new Artifact();
+    artifactValues.set(artifact, value);
+    return Object.freeze(artifact);
+}
+/** @internal */
+export function unwrapArtifact(artifact) {
+    const value = artifactValues.get(artifact);
+    if (value === undefined)
+        throw new TypeError("invalid Flowersec artifact handle");
+    return value;
+}

package/dist/public/artifactLease.d.ts

@@ -0,0 +1,10 @@
+import { type Artifact } from "./artifact.js";
+export declare class ArtifactLeaseError extends Error {
+    readonly code = "already_consumed";
+    constructor();
+}
+export declare class ArtifactLease {
+    #private;
+    private constructor();
+}
+export declare function createArtifactLease(artifact: Artifact, commitSpend: (signal?: AbortSignal) => Promise<void>): ArtifactLease;

package/dist/public/artifactLease.js

@@ -0,0 +1,48 @@
+import { validateArtifactV2 } from "../v2/artifact.js";
+import { unwrapArtifact } from "./artifact.js";
+export class ArtifactLeaseError extends Error {
+    code = "already_consumed";
+    constructor() {
+        super("Flowersec artifact lease has already been consumed");
+        this.name = "ArtifactLeaseError";
+    }
+}
+export class ArtifactLease {
+    #artifactLeaseBrand = undefined;
+    constructor() {
+        Object.freeze(this);
+    }
+    /** @internal */
+    static create() {
+        return new ArtifactLease();
+    }
+}
+const artifactLeaseStates = new WeakMap();
+export function createArtifactLease(artifact, commitSpend) {
+    validateArtifactV2(unwrapArtifact(artifact));
+    const lease = ArtifactLease.create();
+    artifactLeaseStates.set(lease, { artifact, state: "idle", commitSpend });
+    return lease;
+}
+/** @internal Connector-owned access to validated lease material. */
+export function artifactLeaseArtifact(lease) {
+    const leaseState = artifactLeaseStates.get(lease);
+    if (leaseState === undefined)
+        throw new ArtifactLeaseError();
+    return leaseState.artifact;
+}
+/** @internal Connector-owned durable spend transition. */
+export async function commitArtifactLeaseSpend(lease, signal) {
+    const leaseState = artifactLeaseStates.get(lease);
+    if (leaseState === undefined || leaseState.state !== "idle")
+        throw new ArtifactLeaseError();
+    leaseState.state = "spending";
+    try {
+        await leaseState.commitSpend(signal);
+        leaseState.state = "consumed";
+    }
+    catch (error) {
+        leaseState.state = "idle";
+        throw error;
+    }
+}

package/dist/public/connectError.d.ts

@@ -0,0 +1,6 @@
+export type ConnectErrorCode = "invalid_input" | "invalid_options" | "expired_artifact" | "resolve_failed" | "credential_spend_failed" | "connection_failed" | "timeout" | "canceled" | "handshake_failed" | "rpc_failed" | "resource_exhausted" | "not_connected";
+/** A stable connection failure that retains no carrier or credential details. */
+export declare class ConnectError extends Error {
+    readonly code: ConnectErrorCode;
+    constructor(code: ConnectErrorCode);
+}

package/dist/public/connectError.js

@@ -0,0 +1,9 @@
+/** A stable connection failure that retains no carrier or credential details. */
+export class ConnectError extends Error {
+    code;
+    constructor(code) {
+        super(`Flowersec connection failed (code=${code})`);
+        this.code = code;
+        this.name = "ConnectError";
+    }
+}