@floegence/flowersec-core 0.27.0 → 2.0.0

package/dist/cli.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { createArtifactLeaseV2 } from "./v2/artifactLease.js";
+import { buildFSB2RequestV2, encodeFSB2RequestV2 } from "./v2/artifact.js";
+import { parseArtifact, unwrapArtifact } from "./v2/opaqueArtifact.js";
+import { connect } from "./node/connectSession.js";
+import { startNodeWebTransportServerV2 } from "./node/webTransportServer.js";
+import { acceptNativeSessionV2 } from "./connector/sessionAcceptor.js";
+import { nodeSessionRuntimeV2 } from "./node/sessionRuntime.js";
+import { claimSpendMarker } from "./cliSpendMarker.js";
+const args = parseArguments(process.argv.slice(2));
+if (args.mode === "client")
+    await runClient(args.values);
+else
+    await runServer(args.values);
+async function runClient(values) {
+    const artifactPath = required(values, "artifact");
+    const origin = required(values, "origin");
+    const spendMarker = required(values, "spend-marker");
+    requireWebTransport(values);
+    const artifact = parseArtifact(readFileSync(artifactPath));
+    let session;
+    const lease = createArtifactLeaseV2(artifact, async () => claimSpendMarker(spendMarker));
+    try {
+        session = await connect(lease, {
+            origin,
+            ...(values["certificate-hash"] === undefined ? {} : {
+                tls: { serverCertificateHash: decodeHash(values["certificate-hash"]) },
+            }),
+        });
+        const stream = await session.openStream("cli");
+        await stream.write(new TextEncoder().encode("flowersec-ts-cli"));
+        await stream.closeWrite();
+        const response = await stream.read();
+        if (response === null || new TextDecoder().decode(response) !== "flowersec-ts-cli") {
+            throw new Error("CLI server returned an invalid stream response");
+        }
+        process.stdout.write("GREEN\n");
+    }
+    finally {
+        await session?.close();
+    }
+}
+async function runServer(values) {
+    const artifact = unwrapArtifact(parseArtifact(readFileSync(required(values, "artifact"))));
+    requireWebTransport(values);
+    const server = await startNodeWebTransportServerV2({
+        host: values.host ?? "127.0.0.1",
+        port: Number.parseInt(required(values, "port"), 10),
+        path: values.path ?? "/flowersec/webtransport/v2/direct",
+        certificate: readFileSync(required(values, "certificate"), "utf8"),
+        privateKey: readFileSync(required(values, "private-key"), "utf8"),
+        carrierPath: artifact.path.kind,
+        inboundBidirectionalStreamCapacity: artifact.session.max_inbound_streams + 2,
+    });
+    process.stdout.write(JSON.stringify(server.address()) + "\n");
+    const abort = new AbortController();
+    const stop = () => abort.abort(new Error("CLI server stopped"));
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    try {
+        const session = await acceptNativeSessionV2(await server.accept({ signal: abort.signal }), async (request) => {
+            const chosen = artifact.path.candidates.find(({ id }) => id === request.request.chosen_candidate_id);
+            if (request.request.pathKind !== artifact.path.kind || chosen?.carrier !== "webtransport") {
+                throw new Error("CLI server rejected an unexpected artifact candidate");
+            }
+            const expected = encodeFSB2RequestV2(buildFSB2RequestV2(artifact, request.request.chosen_candidate_id));
+            if (!bytesEqual(expected, request.raw))
+                throw new Error("CLI server rejected an unbound artifact");
+            return { accepted: true, artifact };
+        }, { runtime: nodeSessionRuntimeV2, signal: abort.signal });
+        await echoOnce(session);
+        await session.close();
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+        await server.close();
+    }
+}
+async function echoOnce(session) {
+    const incoming = await session.acceptStream();
+    const payload = await incoming.stream.read();
+    if (payload === null)
+        throw new Error("CLI stream closed before payload");
+    await incoming.stream.write(payload);
+    await incoming.stream.closeWrite();
+}
+function parseArguments(raw) {
+    const [mode, ...rest] = raw;
+    if (mode !== "client" && mode !== "server")
+        throw new Error("usage: flowersec-ts-cli <client|server> options");
+    const values = {};
+    for (let index = 0; index < rest.length; index++) {
+        const token = rest[index];
+        if (!token.startsWith("--") || index + 1 >= rest.length || rest[index + 1].startsWith("--")) {
+            throw new Error(`invalid CLI option ${token}`);
+        }
+        values[token.slice(2)] = rest[++index];
+    }
+    return { mode, values };
+}
+function required(values, name) {
+    const value = values[name];
+    if (value === undefined || value === "")
+        throw new Error(`missing --${name}`);
+    return value;
+}
+function decodeHash(value) {
+    if (!/^[0-9a-fA-F]{64}$/.test(value))
+        throw new Error("--certificate-hash must be 32-byte SHA-256 hex");
+    return Uint8Array.from(Buffer.from(value, "hex"));
+}
+function requireWebTransport(values) {
+    if (values.transport !== "webtransport") {
+        throw new Error("--transport webtransport is required");
+    }
+}
+function bytesEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    let different = 0;
+    for (let index = 0; index < left.length; index++)
+        different |= left[index] ^ right[index];
+    return different === 0;
+}

package/dist/cliSpendMarker.d.ts

@@ -0,0 +1 @@
+export declare function claimSpendMarker(path: string): void;

package/dist/cliSpendMarker.js

@@ -0,0 +1,22 @@
+import { closeSync, fsyncSync, openSync } from "node:fs";
+export function claimSpendMarker(path) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, "wx", 0o600);
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "EEXIST") {
+            throw new Error(`spend marker already exists: ${path}`, { cause: error });
+        }
+        throw error;
+    }
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function isErrnoException(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/connectionController.d.ts

@@ -0,0 +1,54 @@
+import type { ArtifactLease } from "./public/artifactLease.js";
+import type { RetryDisposition, Session, SessionErrorCode } from "./public/contract.js";
+import type { ConnectErrorCode } from "./public/connectError.js";
+export type { RetryDisposition } from "./public/contract.js";
+export type ArtifactSourceResult = Readonly<{
+    kind: "lease";
+    lease: ArtifactLease;
+}> | Readonly<{
+    kind: "failure";
+    code: string;
+    disposition: RetryDisposition;
+}>;
+export type ArtifactSource = Readonly<{
+    acquire(options: Readonly<{
+        signal: AbortSignal;
+    }>): Promise<ArtifactSourceResult>;
+}>;
+export type ConnectionState = "idle" | "connecting" | "connected" | "waiting" | "failed" | "closed";
+export type ConnectionControllerFailure = Readonly<{
+    phase: "artifact";
+    code: string;
+}> | Readonly<{
+    phase: "connect";
+    code: ConnectErrorCode;
+}> | Readonly<{
+    phase: "session";
+    code: SessionErrorCode;
+}>;
+export type ConnectionSnapshot = Readonly<{
+    state: ConnectionState;
+    attempt: number;
+    currentSession?: Session;
+    failure?: ConnectionControllerFailure;
+}>;
+export type ConnectionControllerOptions = Readonly<{
+    maximumAttempts?: number;
+}>;
+export interface ConnectionController {
+    readonly state: ConnectionState;
+    readonly currentSession: Session | undefined;
+    readonly failure: ConnectionControllerFailure | undefined;
+    start(): void;
+    retryNow(): boolean;
+    waitForSession(options?: Readonly<{
+        signal?: AbortSignal;
+    }>): Promise<Session>;
+    subscribe(listener: (snapshot: ConnectionSnapshot) => void): () => void;
+    close(): Promise<void>;
+}
+export declare class ConnectionControllerError extends Error {
+    readonly code: "failed" | "closed" | "canceled";
+    readonly failure: ConnectionControllerFailure | undefined;
+    constructor(code: "failed" | "closed" | "canceled", failure?: ConnectionControllerFailure | undefined);
+}

package/dist/connectionController.js

@@ -0,0 +1,438 @@
+import { ConnectError } from "./public/connectError.js";
+import { retryDispositionForConnectError, retryDispositionForSessionError, } from "./v2/retryDisposition.js";
+import { SDK_DEFAULTS } from "./defaults.js";
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+export class ConnectionControllerError extends Error {
+    code;
+    failure;
+    constructor(code, failure = undefined) {
+        super(`Flowersec connection controller stopped (code=${code})`);
+        this.code = code;
+        this.failure = failure;
+        this.name = "ConnectionControllerError";
+    }
+}
+/** @internal Runtime facades supply the only runtime-specific operation: one one-shot connection attempt. */
+export function createConnectionControllerV2(source, connectOneShot, options = {}) {
+    return new ConnectionControllerV2Impl(source, connectOneShot, options);
+}
+class ConnectionControllerV2Impl {
+    source;
+    connectOneShot;
+    controllerState = "idle";
+    session;
+    lastFailure;
+    currentRetryDisposition;
+    attempt = 0;
+    consecutiveFailures = 0;
+    resetAttemptOnRetry = false;
+    lifetime = new AbortController();
+    listeners = new Set();
+    issuedLeases = new WeakSet();
+    issuedSessions = new WeakSet();
+    maxAttempts;
+    scheduler;
+    closeOperation;
+    pendingConnectCleanup;
+    pendingAcquisitionCleanup;
+    waitingWake;
+    manualRetryRequested = false;
+    retryNotBefore = 0;
+    constructor(source, connectOneShot, options) {
+        this.source = source;
+        this.connectOneShot = connectOneShot;
+        if (source === null || typeof source !== "object" || typeof source.acquire !== "function") {
+            throw new TypeError("artifact source must provide acquire()");
+        }
+        if (typeof connectOneShot !== "function")
+            throw new TypeError("one-shot connector is required");
+        if (options.maximumAttempts !== undefined &&
+            (!Number.isSafeInteger(options.maximumAttempts) || options.maximumAttempts < 1)) {
+            throw new TypeError("maximumAttempts must be a positive safe integer");
+        }
+        this.maxAttempts = options.maximumAttempts;
+    }
+    get state() { return this.controllerState; }
+    get currentSession() { return this.connectedSession(); }
+    get failure() { return this.lastFailure; }
+    start() {
+        if (this.controllerState !== "idle")
+            return;
+        this.scheduler = this.run();
+    }
+    retryNow() {
+        if (this.controllerState !== "waiting" || Date.now() < this.retryNotBefore)
+            return false;
+        this.manualRetryRequested = true;
+        this.waitingWake?.();
+        return true;
+    }
+    async waitForSession(options = {}) {
+        const ready = this.connectedSession();
+        if (ready !== undefined)
+            return ready;
+        if (this.controllerState === "failed")
+            throw new ConnectionControllerError("failed", this.lastFailure);
+        if (this.controllerState === "closed")
+            throw new ConnectionControllerError("closed", this.lastFailure);
+        if (options.signal?.aborted === true)
+            throw new ConnectionControllerError("canceled");
+        return await new Promise((resolve, reject) => {
+            const finish = (result) => {
+                this.listeners.delete(listener);
+                options.signal?.removeEventListener("abort", canceled);
+                if (result.session !== undefined)
+                    resolve(result.session);
+                else
+                    reject(result.error ?? new ConnectionControllerError("failed", this.lastFailure));
+            };
+            const listener = (snapshot) => {
+                if (snapshot.state === "connected" && snapshot.currentSession !== undefined) {
+                    finish({ session: snapshot.currentSession });
+                }
+                else if (snapshot.state === "failed") {
+                    finish({ error: new ConnectionControllerError("failed", snapshot.failure) });
+                }
+                else if (snapshot.state === "closed") {
+                    finish({ error: new ConnectionControllerError("closed", snapshot.failure) });
+                }
+            };
+            const canceled = () => finish({ error: new ConnectionControllerError("canceled") });
+            this.listeners.add(listener);
+            options.signal?.addEventListener("abort", canceled, { once: true });
+        });
+    }
+    subscribe(listener) {
+        if (typeof listener !== "function")
+            throw new TypeError("connection listener must be a function");
+        this.listeners.add(listener);
+        try {
+            listener(this.snapshot());
+        }
+        catch (error) {
+            this.listeners.delete(listener);
+            throw error;
+        }
+        return () => { this.listeners.delete(listener); };
+    }
+    close() {
+        if (this.closeOperation !== undefined)
+            return this.closeOperation;
+        let resolveClose;
+        this.closeOperation = new Promise((resolve) => {
+            resolveClose = resolve;
+        });
+        const active = this.session;
+        // A closed controller must never advertise a session that it has just retired.
+        this.session = undefined;
+        this.lifetime.abort(new ConnectionControllerError("closed", this.lastFailure));
+        this.transition("closed");
+        void this.finishClose(active).then(resolveClose);
+        return this.closeOperation;
+    }
+    async finishClose(active) {
+        this.waitingWake?.();
+        const activeClose = active === undefined
+            ? Promise.resolve()
+            : active.close();
+        await Promise.allSettled([this.scheduler ?? Promise.resolve(), activeClose]);
+        const pendingCleanup = this.pendingConnectCleanup;
+        const acquisitionCleanup = this.pendingAcquisitionCleanup;
+        await Promise.allSettled([
+            ...(pendingCleanup === undefined ? [] : [pendingCleanup]),
+            ...(acquisitionCleanup === undefined ? [] : [acquisitionCleanup]),
+        ]);
+    }
+    async run() {
+        let disposition;
+        while (!this.lifetime.signal.aborted) {
+            if (disposition !== undefined) {
+                const canContinue = await this.waitForRetry(disposition);
+                if (!canContinue)
+                    return;
+            }
+            if (this.maxAttempts !== undefined && this.attempt >= this.maxAttempts) {
+                this.currentRetryDisposition = Object.freeze({ kind: "terminal" });
+                this.transition("failed");
+                return;
+            }
+            this.attempt += 1;
+            this.transition("connecting");
+            const acquisition = await this.acquireLease();
+            if (this.lifetime.signal.aborted)
+                return;
+            if (acquisition.kind === "failure") {
+                this.lastFailure = Object.freeze({ phase: "artifact", code: acquisition.code });
+                disposition = acquisition.disposition;
+                this.currentRetryDisposition = disposition;
+                if (disposition.kind === "terminal") {
+                    this.transition("failed");
+                    return;
+                }
+                this.consecutiveFailures += 1;
+                continue;
+            }
+            let connected;
+            try {
+                connected = await this.connect(acquisition.lease);
+            }
+            catch (error) {
+                if (this.lifetime.signal.aborted)
+                    return;
+                const failure = connectFailure(error);
+                this.lastFailure = failure.failure;
+                disposition = failure.disposition;
+                this.currentRetryDisposition = disposition;
+                if (disposition.kind === "terminal") {
+                    this.transition("failed");
+                    return;
+                }
+                this.consecutiveFailures += 1;
+                continue;
+            }
+            if (this.lifetime.signal.aborted) {
+                await connected.close().catch(() => undefined);
+                return;
+            }
+            this.session = connected;
+            this.lastFailure = undefined;
+            this.currentRetryDisposition = undefined;
+            this.consecutiveFailures = 0;
+            disposition = undefined;
+            this.transition("connected");
+            const termination = await raceTermination(connected, this.lifetime.signal);
+            if (termination === undefined || this.lifetime.signal.aborted)
+                return;
+            // A terminated session is no longer current while the replacement attempt waits.
+            this.session = undefined;
+            await connected.close().catch(() => undefined);
+            if (this.lifetime.signal.aborted)
+                return;
+            const failure = sessionFailure(termination.error);
+            this.lastFailure = failure.failure;
+            disposition = failure.disposition;
+            this.currentRetryDisposition = disposition;
+            if (disposition.kind === "terminal") {
+                this.transition("failed");
+                return;
+            }
+            this.consecutiveFailures = 1;
+            this.resetAttemptOnRetry = true;
+        }
+    }
+    async acquireLease() {
+        let result;
+        let pending;
+        try {
+            pending = this.source.acquire({ signal: this.lifetime.signal });
+        }
+        catch {
+            return terminalArtifactFailure("artifact_source_failed");
+        }
+        const cleanup = pending.then(() => undefined, () => undefined);
+        this.pendingAcquisitionCleanup = cleanup;
+        void cleanup.finally(() => {
+            if (this.pendingAcquisitionCleanup === cleanup)
+                this.pendingAcquisitionCleanup = undefined;
+        }).catch(() => undefined);
+        try {
+            result = await raceAbort(pending, this.lifetime.signal);
+        }
+        catch {
+            return terminalArtifactFailure("artifact_source_failed");
+        }
+        try {
+            if (result === null || typeof result !== "object")
+                return terminalArtifactFailure("artifact_source_failed");
+            if (result.kind === "failure") {
+                if (!validFailureCode(result.code) || !validDisposition(result.disposition)) {
+                    return terminalArtifactFailure("artifact_source_failed");
+                }
+                return Object.freeze({ kind: "failure", code: result.code, disposition: normalizeDisposition(result.disposition) });
+            }
+            if (result.kind !== "lease" || result.lease === null || typeof result.lease !== "object") {
+                return terminalArtifactFailure("artifact_source_failed");
+            }
+            if (this.issuedLeases.has(result.lease))
+                return terminalArtifactFailure("reused_artifact_lease");
+            this.issuedLeases.add(result.lease);
+            return result;
+        }
+        catch {
+            return terminalArtifactFailure("artifact_source_failed");
+        }
+    }
+    async connect(lease) {
+        const pending = this.connectOneShot(lease, this.lifetime.signal);
+        try {
+            const session = await raceAbort(pending, this.lifetime.signal);
+            if (session === null || typeof session !== "object" ||
+                typeof session.close !== "function" || typeof session.waitTermination !== "function") {
+                throw new TypeError("one-shot connector returned an invalid session");
+            }
+            if (this.issuedSessions.has(session)) {
+                await session.close().catch(() => undefined);
+                throw new Error("one-shot connector reused a previous session");
+            }
+            this.issuedSessions.add(session);
+            return session;
+        }
+        catch (error) {
+            if (this.lifetime.signal.aborted) {
+                const cleanup = pending.then(async (lateSession) => await lateSession.close(), () => undefined);
+                this.pendingConnectCleanup = cleanup;
+                void cleanup.finally(() => {
+                    if (this.pendingConnectCleanup === cleanup)
+                        this.pendingConnectCleanup = undefined;
+                }).catch(() => undefined);
+            }
+            throw error;
+        }
+    }
+    async waitForRetry(disposition) {
+        if (this.maxAttempts !== undefined && !this.resetAttemptOnRetry && this.attempt >= this.maxAttempts) {
+            this.currentRetryDisposition = Object.freeze({ kind: "terminal" });
+            this.transition("failed");
+            return false;
+        }
+        const now = Date.now();
+        const backoffDeadline = now + retryDelay(this.consecutiveFailures);
+        const hardDeadline = disposition.kind === "retry_after"
+            ? disposition.notBeforeUnixMilliseconds
+            : 0;
+        this.retryNotBefore = hardDeadline;
+        this.manualRetryRequested = false;
+        this.transition("waiting");
+        while (!this.lifetime.signal.aborted) {
+            const deadline = this.manualRetryRequested
+                ? hardDeadline
+                : Math.max(backoffDeadline, hardDeadline);
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                this.waitingWake = undefined;
+                this.retryNotBefore = 0;
+                if (this.resetAttemptOnRetry) {
+                    this.attempt = 0;
+                    this.resetAttemptOnRetry = false;
+                }
+                return true;
+            }
+            await this.wait(Math.min(remaining, MAX_TIMER_DELAY_MS));
+        }
+        this.waitingWake = undefined;
+        this.retryNotBefore = 0;
+        return false;
+    }
+    async wait(milliseconds) {
+        await new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.lifetime.signal.removeEventListener("abort", finish);
+                if (this.waitingWake === finish)
+                    this.waitingWake = undefined;
+                resolve();
+            };
+            const timer = setTimeout(finish, milliseconds);
+            this.waitingWake = finish;
+            this.lifetime.signal.addEventListener("abort", finish, { once: true });
+        });
+    }
+    connectedSession() {
+        return this.controllerState === "connected" ? this.session : undefined;
+    }
+    transition(state) {
+        this.controllerState = state;
+        const snapshot = this.snapshot();
+        for (const listener of this.listeners) {
+            try {
+                listener(snapshot);
+            }
+            catch { /* Listener failures do not own controller lifecycle. */ }
+        }
+    }
+    snapshot() {
+        const currentSession = this.connectedSession();
+        return Object.freeze({
+            state: this.controllerState,
+            attempt: this.attempt,
+            ...(currentSession === undefined ? {} : { currentSession }),
+            ...(this.lastFailure === undefined ? {} : { failure: this.lastFailure }),
+        });
+    }
+}
+function connectFailure(error) {
+    if (!(error instanceof ConnectError)) {
+        return Object.freeze({
+            failure: Object.freeze({ phase: "connect", code: "connection_failed" }),
+            disposition: Object.freeze({ kind: "terminal" }),
+        });
+    }
+    const disposition = retryDispositionForConnectError(error);
+    return Object.freeze({
+        failure: Object.freeze({ phase: "connect", code: error.code }),
+        disposition,
+    });
+}
+function sessionFailure(error) {
+    const disposition = retryDispositionForSessionError(error);
+    return Object.freeze({
+        failure: Object.freeze({ phase: "session", code: error.code }),
+        disposition,
+    });
+}
+function terminalArtifactFailure(code) {
+    return Object.freeze({
+        kind: "failure",
+        code,
+        disposition: Object.freeze({ kind: "terminal" }),
+    });
+}
+function validFailureCode(code) {
+    return typeof code === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(code);
+}
+function validDisposition(value) {
+    if (value === null || typeof value !== "object" || !("kind" in value))
+        return false;
+    const disposition = value;
+    if (disposition.kind === "terminal" || disposition.kind === "retryable")
+        return true;
+    return disposition.kind === "retry_after" &&
+        typeof disposition.notBeforeUnixMilliseconds === "number" &&
+        Number.isSafeInteger(disposition.notBeforeUnixMilliseconds) &&
+        disposition.notBeforeUnixMilliseconds >= 0;
+}
+function normalizeDisposition(disposition) {
+    if (disposition.kind === "retry_after") {
+        return Object.freeze({
+            kind: "retry_after",
+            notBeforeUnixMilliseconds: disposition.notBeforeUnixMilliseconds,
+        });
+    }
+    return Object.freeze({ kind: disposition.kind });
+}
+function retryDelay(failures) {
+    const exponent = Math.max(0, Math.min(30, failures - 1));
+    return Math.min(SDK_DEFAULTS.connectionController.maxDelayMs, SDK_DEFAULTS.connectionController.initialDelayMs *
+        (SDK_DEFAULTS.connectionController.factor ** exponent));
+}
+async function raceAbort(promise, signal) {
+    if (signal.aborted)
+        throw signal.reason;
+    return await new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}
+async function raceTermination(session, signal) {
+    try {
+        return await raceAbort(session.waitTermination(), signal);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/connector/adapters/webSocketCandidate.d.ts

@@ -0,0 +1,7 @@
+import type { CandidateAttemptFactoryV2 } from "../sessionConnector.js";
+import { type WebSocketLike } from "../../ws-client/binaryTransport.js";
+type WebSocketLikeWithProtocol = WebSocketLike & Readonly<{
+    protocol?: string;
+}>;
+export declare function createWebSocketCandidateFactoryV2(factory: (url: string, subprotocol: string) => WebSocketLikeWithProtocol): CandidateAttemptFactoryV2;
+export {};