@floegence/flowersec-core 2.5.4 → 3.0.0

package/dist/v3/publicApi.d.ts

@@ -0,0 +1,12 @@
+import { type ArtifactLeaseV3 } from "./artifactLease.js";
+export declare class ArtifactHandleV3 {
+    private readonly artifactHandleBrand;
+    private constructor();
+}
+export type ArtifactParseErrorCodeV3 = "artifact_too_large" | "invalid_artifact";
+export declare class ArtifactParseErrorV3 extends Error {
+    readonly code: ArtifactParseErrorCodeV3;
+    constructor(code: ArtifactParseErrorCodeV3);
+}
+export declare function parseArtifactV3(input: string | Uint8Array): ArtifactHandleV3;
+export declare function createArtifactLeaseV3(artifact: ArtifactHandleV3, commitSpend: (signal?: AbortSignal) => Promise<void>, retireCleanup?: () => Promise<void>): ArtifactLeaseV3;

package/dist/v3/publicApi.js

@@ -0,0 +1,46 @@
+import { ArtifactV3Error, decodeArtifactV3JSON, validateArtifactV3, } from "./artifact.js";
+import { createArtifactLeaseV3Internal, } from "./artifactLease.js";
+const artifacts = new WeakMap();
+export class ArtifactHandleV3 {
+    constructor() { }
+}
+export class ArtifactParseErrorV3 extends Error {
+    code;
+    constructor(code) {
+        super(`Flowersec v3 artifact parsing failed (code=${code})`);
+        this.code = code;
+        this.name = "ArtifactError";
+    }
+}
+export function parseArtifactV3(input) {
+    try {
+        const value = decodeArtifactV3JSON(input);
+        const handle = new ArtifactHandleV3();
+        artifacts.set(handle, value);
+        return Object.freeze(handle);
+    }
+    catch (error) {
+        throw new ArtifactParseErrorV3(error instanceof ArtifactV3Error && error.code === "artifact_too_large"
+            ? "artifact_too_large"
+            : "invalid_artifact");
+    }
+}
+export function createArtifactLeaseV3(artifact, commitSpend, retireCleanup) {
+    const value = artifacts.get(artifact);
+    if (value === undefined)
+        throw new ArtifactParseErrorV3("invalid_artifact");
+    try {
+        validateArtifactV3(value);
+        return createArtifactLeaseV3Internal(value, commitSpend, retireCleanup);
+    }
+    catch {
+        throw new ArtifactParseErrorV3("invalid_artifact");
+    }
+}
+/** @internal */
+export function unwrapArtifactHandleV3(handle) {
+    const value = artifacts.get(handle);
+    if (value === undefined)
+        throw new ArtifactParseErrorV3("invalid_artifact");
+    return value;
+}

package/dist/v3/publicSession.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/v3/publicSession.js

@@ -0,0 +1,281 @@
+import { SessionError } from "./contract.js";
+import { createStreamMetadataV3, streamMetadataValuesV3 } from "./streamMetadata.js";
+import { assertRpcTypeId } from "../rpc/validate.js";
+/** @internal */
+export function projectSessionV3(session) {
+    const notificationOwner = {
+        subscriptions: new Set(),
+        closed: false,
+    };
+    const clearNotificationSubscriptions = () => {
+        notificationOwner.closed = true;
+        for (const unsubscribe of [...notificationOwner.subscriptions])
+            unsubscribe();
+    };
+    const rpc = projectRpcPeerV3(session.rpc, notificationOwner);
+    const unreliable = session.unreliableMessages;
+    void session.termination.then(clearNotificationSubscriptions, clearNotificationSubscriptions);
+    return Object.freeze({
+        rpc,
+        ...(unreliable === undefined ? {} : { unreliableMessages: unreliable }),
+        async openStream(kind, options) {
+            try {
+                const internalOptions = options === undefined ? undefined : {
+                    ...(options.signal === undefined ? {} : { signal: options.signal }),
+                    ...(options.metadata === undefined ? {} : { metadata: streamMetadataValuesV3(options.metadata) }),
+                };
+                return projectByteStreamV3(await session.openStream(kind, internalOptions));
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async acceptStream(options) {
+            try {
+                const incoming = await session.acceptStream(options);
+                return Object.freeze({
+                    kind: incoming.kind,
+                    metadata: createStreamMetadataV3(incoming.metadata),
+                    stream: projectByteStreamV3(incoming.stream),
+                });
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async rekey(options) {
+            try {
+                await session.rekey(options);
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async probeLiveness(options) {
+            try {
+                return await session.probeLiveness(options);
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async waitTermination(options) {
+            try {
+                const { error } = await raceWithSignal(session.waitTermination(), options?.signal);
+                return Object.freeze({ error: redactSessionError(error) });
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async close() {
+            try {
+                await session.close();
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+            finally {
+                clearNotificationSubscriptions();
+            }
+        },
+    });
+}
+function projectByteStreamV3(stream) {
+    return Object.freeze({
+        kind: stream.kind,
+        get terminalError() {
+            return stream.terminalError === undefined ? undefined : redactSessionError(stream.terminalError);
+        },
+        async read(options) {
+            try {
+                return await stream.read(options);
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async write(data, options) {
+            try {
+                return await stream.write(data, options);
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async closeWrite() {
+            try {
+                await stream.closeWrite();
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async reset() {
+            try {
+                await stream.reset();
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async close() {
+            try {
+                await stream.close();
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+    });
+}
+function projectRpcPeerV3(peer, notificationOwner) {
+    return Object.freeze({
+        async call(typeId, payload, decodeResponse, options) {
+            try {
+                assertRpcTypeId(typeId);
+                assertJsonValue(payload);
+                const result = await peer.call(typeId, payload, options?.signal);
+                if (result.error !== undefined) {
+                    return Object.freeze({ ok: false, error: Object.freeze({ ...result.error }) });
+                }
+                assertJsonValue(result.payload);
+                return Object.freeze({ ok: true, payload: decodeResponse(result.payload) });
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async notify(typeId, payload, options) {
+            try {
+                assertRpcTypeId(typeId);
+                assertJsonValue(payload);
+                if (options?.signal?.aborted)
+                    throw options.signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+                await raceWithSignal(peer.notify(typeId, payload), options?.signal);
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        onNotify(typeId, decodePayload, handler) {
+            assertRpcTypeId(typeId);
+            if (notificationOwner.closed)
+                return () => undefined;
+            const unsubscribe = peer.onNotify(typeId, (payload) => {
+                let decoded;
+                try {
+                    assertJsonValue(payload);
+                    decoded = decodePayload(payload);
+                }
+                catch {
+                    return;
+                }
+                try {
+                    void Promise.resolve(handler(decoded)).catch(() => undefined);
+                }
+                catch {
+                    // Notification handlers are isolated from RPC serving.
+                }
+            });
+            let subscribed = true;
+            const cancel = () => {
+                if (!subscribed)
+                    return;
+                subscribed = false;
+                notificationOwner.subscriptions.delete(cancel);
+                unsubscribe();
+            };
+            notificationOwner.subscriptions.add(cancel);
+            return cancel;
+        },
+    });
+}
+function assertJsonValue(value) {
+    validateJsonValue(value, new Set());
+}
+function validateJsonValue(value, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return;
+        throw new TypeError("RPC payload contains a non-finite number");
+    }
+    if (typeof value !== "object")
+        throw new TypeError("RPC payload is not a JSON value");
+    if (ancestors.has(value))
+        throw new TypeError("RPC payload contains a cycle");
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index += 1) {
+                if (!(index in value))
+                    throw new TypeError("RPC payload contains a sparse array");
+                validateJsonValue(value[index], ancestors);
+            }
+            return;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("RPC payload contains a non-JSON object");
+        }
+        for (const key of Object.keys(value)) {
+            validateJsonValue(value[key], ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+async function raceWithSignal(operation, signal) {
+    if (signal === undefined)
+        return await operation;
+    if (signal.aborted)
+        throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+    return await new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason ?? new DOMException("The operation was aborted", "AbortError"));
+        signal.addEventListener("abort", abort, { once: true });
+        void operation.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}
+function redactSessionError(error) {
+    if (error instanceof SessionError)
+        return error;
+    return new SessionError(sessionErrorCode(error));
+}
+function sessionErrorCode(error) {
+    if (error instanceof DOMException && error.name === "AbortError")
+        return "canceled";
+    if (error instanceof Error) {
+        if (error.name === "AbortError")
+            return "canceled";
+        if (error.name === "TimeoutError")
+            return "timeout";
+        const code = error.code;
+        if (error.name === "CarrierError" || typeof code === "string") {
+            if (code === "closed" || code === "carrier_closed")
+                return "closed";
+            if (code === "aborted" || code === "operation_aborted")
+                return "canceled";
+            if (code === "reset" || code === "stream_reset")
+                return "stream_reset";
+        }
+        if (error.name === "SessionV3Error") {
+            const code = error.code;
+            switch (code) {
+                case "aborted": return "canceled";
+                case "timeout": return "timeout";
+                case "closed": return "closed";
+                case "going_away": return "going_away";
+                case "open_rejected": return "stream_rejected";
+                case "stream_reset": return "stream_reset";
+                case "resource_exhausted": return "resource_exhausted";
+                case "rekey_failed": return "rekey_failed";
+                case "liveness_failed": return "liveness_failed";
+                default: return "operation_failed";
+            }
+        }
+    }
+    return "operation_failed";
+}

package/dist/v3/retryDisposition.d.ts

@@ -0,0 +1,16 @@
+import type { SessionErrorCode } from "./contract.js";
+import type { ConnectErrorCode } from "../public/connectError.js";
+export type RetryDisposition = Readonly<{
+    kind: "terminal";
+}> | Readonly<{
+    kind: "retryable";
+}> | Readonly<{
+    kind: "retry_after";
+    notBeforeUnixMilliseconds: number;
+}>;
+export declare function retryDispositionForConnectError(error: Readonly<{
+    code: ConnectErrorCode;
+}>): RetryDisposition;
+export declare function retryDispositionForSessionError(error: Readonly<{
+    code: SessionErrorCode;
+}>): RetryDisposition;

package/dist/v3/retryDisposition.js

@@ -0,0 +1,30 @@
+export function retryDispositionForConnectError(error) {
+    switch (error.code) {
+        case "expired_artifact":
+        case "resolve_failed":
+        case "credential_spend_failed":
+        case "connection_failed":
+        case "timeout":
+        case "handshake_failed":
+        case "rpc_failed":
+        case "resource_exhausted":
+        case "not_connected":
+            return Object.freeze({ kind: "retryable" });
+        default:
+            return Object.freeze({ kind: "terminal" });
+    }
+}
+export function retryDispositionForSessionError(error) {
+    switch (error.code) {
+        case "closed":
+        case "going_away":
+        case "timeout":
+        case "resource_exhausted":
+        case "stream_reset":
+        case "rekey_failed":
+        case "liveness_failed":
+            return Object.freeze({ kind: "retryable" });
+        default:
+            return Object.freeze({ kind: "terminal" });
+    }
+}

package/dist/v3/runtimeAdapters.d.ts

@@ -0,0 +1,9 @@
+import { type WebSocketLike } from "../ws-client/binaryTransport.js";
+import type { ArtifactV3, CanonicalArtifactCandidateV3 } from "./artifact.js";
+import { type NativeCarrierSessionV3 } from "./carrier.js";
+import type { ReadyAdmissionTransportV3 } from "./sessionConnector.js";
+export type WebSocketLikeV3 = WebSocketLike & Readonly<{
+    protocol?: string;
+}>;
+export declare function readyWebSocketAdmissionV3(candidate: CanonicalArtifactCandidateV3, artifact: ArtifactV3, socket: WebSocketLikeV3, signal: AbortSignal): Promise<ReadyAdmissionTransportV3>;
+export declare function readyNativeAdmissionV3(candidate: CanonicalArtifactCandidateV3, carrier: NativeCarrierSessionV3): ReadyAdmissionTransportV3;

package/dist/v3/runtimeAdapters.js

@@ -0,0 +1,109 @@
+import { WebSocketBinaryTransport } from "../ws-client/binaryTransport.js";
+import { adaptNativeCarrierSessionV3, } from "./carrier.js";
+import { TransportFailureV3 } from "./security.js";
+import { createWebSocketCarrierSessionV3 } from "./webSocketCarrier.js";
+import { websocketSubprotocolForPathV3 } from "./transportConstants.js";
+export async function readyWebSocketAdmissionV3(candidate, artifact, socket, signal) {
+    const subprotocol = websocketSubprotocolForPathV3(artifact.path.kind);
+    await waitForWebSocketOpen(socket, subprotocol, signal);
+    const transport = new WebSocketBinaryTransport(socket);
+    let finalized = false;
+    return {
+        candidate,
+        openAdmissionChannel: async () => ({
+            framing: "message",
+            write: async (data, operationSignal) => await transport.writeBinary(data, operationSignal === undefined ? {} : { signal: operationSignal }),
+            read: async (operationSignal) => await transport.readBinary(operationSignal === undefined ? {} : { signal: operationSignal }),
+            abort: () => transport.close(),
+        }),
+        finalize: () => {
+            if (finalized)
+                throw new TransportFailureV3("connection_failed");
+            finalized = true;
+            return createWebSocketCarrierSessionV3(transport, {
+                path: artifact.path.kind,
+                client: artifact.path.kind !== "tunnel" || artifact.path.role !== 2,
+                inboundBidirectionalStreamCapacity: artifact.session.max_inbound_streams + 2,
+            });
+        },
+        close: async () => transport.close(),
+        abort: () => transport.close(),
+    };
+}
+export function readyNativeAdmissionV3(candidate, carrier) {
+    let finalized = false;
+    return {
+        candidate,
+        openAdmissionChannel: async (signal) => {
+            const options = signal === undefined ? {} : { signal };
+            const stream = carrier.kind === "webtransport"
+                ? await carrier.acceptStream(options)
+                : await carrier.openStream(options);
+            return {
+                framing: "stream",
+                stream,
+                abort: (error) => stream.abort(error),
+            };
+        },
+        finalize: () => {
+            if (finalized)
+                throw new TransportFailureV3("connection_failed");
+            finalized = true;
+            return adaptNativeCarrierSessionV3(carrier);
+        },
+        close: async () => await carrier.close(),
+        abort: () => carrier.abort({ code: 6, reason: "candidate aborted" }),
+    };
+}
+function waitForWebSocketOpen(socket, expectedProtocol, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    if (socket.readyState === 1) {
+        if (socket.protocol === expectedProtocol)
+            return Promise.resolve();
+        closeWebSocketAfterProtocolMismatch(socket);
+        return Promise.reject(new TransportFailureV3("connection_failed"));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            socket.removeEventListener("open", open);
+            socket.removeEventListener("error", error);
+            socket.removeEventListener("close", close);
+            signal.removeEventListener("abort", abort);
+        };
+        const finish = (failure) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            failure === undefined ? resolve() : reject(failure);
+        };
+        const open = () => {
+            if (socket.protocol === expectedProtocol) {
+                finish();
+                return;
+            }
+            closeWebSocketAfterProtocolMismatch(socket);
+            finish(new TransportFailureV3("connection_failed"));
+        };
+        const error = (event) => finish(new TransportFailureV3("connection_failed", undefined, event));
+        const close = () => finish(new TransportFailureV3("connection_failed"));
+        const abort = () => {
+            socket.close();
+            finish(signal.reason);
+        };
+        socket.addEventListener("open", open);
+        socket.addEventListener("error", error);
+        socket.addEventListener("close", close);
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+}
+function closeWebSocketAfterProtocolMismatch(socket) {
+    try {
+        socket.close();
+    }
+    catch { /* best effort cleanup after a failed handshake */ }
+}

package/dist/v3/security.d.ts

@@ -0,0 +1,34 @@
+import type { CertificatePinV3, TransportSecurityPolicyV3 } from "./artifact.js";
+export type TransportFailureCodeV3 = "invalid_artifact" | "expired_artifact" | "tls_unsupported" | "tls_policy_expired" | "tls_failed" | "connection_failed";
+export type TransportFailureDetailV3 = "ca_untrusted" | "pin_mismatch" | "unknown" | "browser_pin_opaque";
+export declare class TransportFailureV3 extends Error {
+    readonly code: TransportFailureCodeV3;
+    readonly detail?: TransportFailureDetailV3 | undefined;
+    constructor(code: TransportFailureCodeV3, detail?: TransportFailureDetailV3 | undefined, cause?: unknown);
+}
+export type PublicConnectErrorCodeV3 = "artifact_invalid" | "expired_artifact" | "transport_security_unsupported" | "transport_security_failed" | "connection_failed";
+export type RetryDispositionV3 = Readonly<{
+    kind: "terminal";
+}> | Readonly<{
+    kind: "retryable";
+}> | Readonly<{
+    kind: "retry_after";
+    absoluteUnixMilliseconds: number;
+}>;
+export declare class ConnectErrorV3 extends Error {
+    readonly code: PublicConnectErrorCodeV3;
+    readonly disposition: RetryDispositionV3;
+    constructor(code: PublicConnectErrorCodeV3, disposition: RetryDispositionV3);
+}
+export type TransportSecuritySnapshotV3 = Readonly<{
+    mode: "ca";
+}> | Readonly<{
+    mode: "pin";
+    activePins: readonly CertificatePinV3[];
+    activeLeafDerSHA256: readonly Uint8Array[];
+}>;
+export declare function snapshotTransportSecurityPolicyV3(policy: TransportSecurityPolicyV3, attemptNowUnixSeconds: number, supportedModes: readonly ("ca" | "pin")[]): TransportSecuritySnapshotV3;
+export declare function projectTransportFailureV3(failure: TransportFailureV3, _policyMode: "ca" | "pin"): ConnectErrorV3;
+export declare function validateRetryDispositionV3(value: RetryDispositionV3): RetryDispositionV3;
+export declare function aggregateRetryDispositionsV3(values: readonly RetryDispositionV3[]): RetryDispositionV3;
+export declare function controllerBackoffMillisecondsV3(consecutiveFailure: number): number;

package/dist/v3/security.js

@@ -0,0 +1,100 @@
+import { base64urlDecode } from "../utils/base64url.js";
+export class TransportFailureV3 extends Error {
+    code;
+    detail;
+    constructor(code, detail, cause) {
+        super("Flowersec v3 transport attempt failed", { cause });
+        this.code = code;
+        this.detail = detail;
+        this.name = "TransportFailureV3";
+    }
+}
+export class ConnectErrorV3 extends Error {
+    code;
+    disposition;
+    constructor(code, disposition) {
+        super(`Flowersec connection failed (code=${code})`);
+        this.code = code;
+        this.disposition = disposition;
+        this.name = "ConnectError";
+    }
+}
+export function snapshotTransportSecurityPolicyV3(policy, attemptNowUnixSeconds, supportedModes) {
+    if (!Number.isSafeInteger(attemptNowUnixSeconds) || attemptNowUnixSeconds < 0) {
+        throw new TransportFailureV3("invalid_artifact");
+    }
+    if (!supportedModes.includes(policy.mode))
+        throw new TransportFailureV3("tls_unsupported");
+    if (policy.mode === "ca")
+        return Object.freeze({ mode: "ca" });
+    const activePins = policy.pins.filter((pin) => attemptNowUnixSeconds < pin.not_after_unix_s);
+    if (activePins.length === 0)
+        throw new TransportFailureV3("tls_policy_expired");
+    let decoded;
+    try {
+        decoded = activePins.map((pin) => {
+            const bytes = base64urlDecode(pin.value_b64u);
+            if (bytes.length !== 32)
+                throw new Error("invalid pin length");
+            return bytes;
+        });
+    }
+    catch (error) {
+        throw new TransportFailureV3("invalid_artifact", undefined, error);
+    }
+    return Object.freeze({
+        mode: "pin",
+        activePins: Object.freeze([...activePins]),
+        activeLeafDerSHA256: Object.freeze(decoded),
+    });
+}
+export function projectTransportFailureV3(failure, _policyMode) {
+    switch (failure.code) {
+        case "invalid_artifact":
+            return new ConnectErrorV3("artifact_invalid", terminal());
+        case "expired_artifact":
+            return new ConnectErrorV3("expired_artifact", retryable());
+        case "tls_unsupported":
+            return new ConnectErrorV3("transport_security_unsupported", terminal());
+        case "tls_policy_expired":
+        case "tls_failed":
+            return new ConnectErrorV3("transport_security_failed", terminal());
+        case "connection_failed":
+            return new ConnectErrorV3("connection_failed", retryable());
+    }
+}
+export function validateRetryDispositionV3(value) {
+    if (value.kind === "terminal")
+        return terminal();
+    if (value.kind === "retryable")
+        return retryable();
+    if (value.kind !== "retry_after" || !Number.isSafeInteger(value.absoluteUnixMilliseconds) ||
+        value.absoluteUnixMilliseconds < 0 || value.absoluteUnixMilliseconds > 253_402_300_799_999) {
+        throw new ConnectErrorV3("artifact_invalid", terminal());
+    }
+    return Object.freeze({ kind: "retry_after", absoluteUnixMilliseconds: value.absoluteUnixMilliseconds });
+}
+export function aggregateRetryDispositionsV3(values) {
+    let latest;
+    let canRetry = false;
+    for (const input of values) {
+        const value = validateRetryDispositionV3(input);
+        if (value.kind === "retry_after")
+            latest = Math.max(latest ?? 0, value.absoluteUnixMilliseconds);
+        else if (value.kind === "retryable")
+            canRetry = true;
+    }
+    if (latest !== undefined)
+        return Object.freeze({ kind: "retry_after", absoluteUnixMilliseconds: latest });
+    return canRetry ? retryable() : terminal();
+}
+export function controllerBackoffMillisecondsV3(consecutiveFailure) {
+    if (!Number.isSafeInteger(consecutiveFailure) || consecutiveFailure < 1) {
+        throw new RangeError("consecutive failure ordinal must be positive");
+    }
+    if (consecutiveFailure >= 8)
+        return 30_000;
+    return Math.min(250 * 2 ** (consecutiveFailure - 1), 30_000);
+}
+const terminal = () => Object.freeze({ kind: "terminal" });
+const retryable = () => Object.freeze({ kind: "retryable" });