@floegence/flowersec-core 0.27.0 → 2.0.0

package/dist/v2/publicSession.d.ts

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

package/dist/v2/publicSession.js

@@ -0,0 +1,179 @@
+import { SessionError } from "./contract.js";
+import { createStreamMetadataV2, streamMetadataValuesV2 } from "./streamMetadata.js";
+/** @internal */
+export function projectSessionV2(session) {
+    const rpc = projectRpcPeerV2(session.rpc);
+    const unreliable = session.unreliableMessages;
+    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: streamMetadataValuesV2(options.metadata) }),
+                };
+                return projectByteStreamV2(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: createStreamMetadataV2(incoming.metadata),
+                    stream: projectByteStreamV2(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() {
+            const { error } = await session.waitTermination();
+            return Object.freeze({ error: redactSessionError(error) });
+        },
+        async close() {
+            try {
+                await session.close();
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+    });
+}
+function projectByteStreamV2(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 projectRpcPeerV2(peer) {
+    return Object.freeze({
+        async call(typeId, payload, decodeResponse, signal) {
+            try {
+                const result = await peer.call(typeId, payload, signal);
+                if (result.error !== undefined) {
+                    return Object.freeze({ ok: false, error: Object.freeze({ ...result.error }) });
+                }
+                return Object.freeze({ ok: true, payload: decodeResponse(result.payload) });
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        async notify(typeId, payload) {
+            try {
+                await peer.notify(typeId, payload);
+            }
+            catch (error) {
+                throw redactSessionError(error);
+            }
+        },
+        onNotify(typeId, handler) {
+            return peer.onNotify(typeId, (payload) => handler(payload));
+        },
+    });
+}
+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 === "SessionV2Error") {
+            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/v2/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/v2/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 { kind: "retryable" };
+        default:
+            return { 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 { kind: "retryable" };
+        default:
+            return { kind: "terminal" };
+    }
+}

package/dist/v2/session.d.ts

@@ -0,0 +1,277 @@
+import { RpcClient } from "../rpc/client.js";
+import { RpcRouter, type RpcServerOptions } from "../rpc/server.js";
+import type { InternalByteStreamV2 as ByteStreamV2, InternalIncomingStreamV2 as IncomingStreamV2, InternalSessionV2 as SessionV2Contract, OperationOptionsV2, PathKind, InternalStreamOpenOptionsV2, UnreliableMessageChannelV2 } from "./contract.js";
+import { type CarrierSessionV2, type CarrierStreamV2 } from "./carrier.js";
+import type { SessionContractV2 } from "./artifact.js";
+import { DirectionV2, InnerTypeV2, type EpochRootsV2, type RecordHeaderV2, type CipherSuiteV2 } from "./protocol.js";
+type SessionTerminationV2 = Readonly<{
+    error: Error;
+}>;
+export type SessionRoleV2 = "client" | "server";
+export type SessionDeadlinePhaseV2 = "establish" | "rekey_prepare" | "rekey_completion";
+export type SessionDeadlineHandleV2 = Readonly<{
+    signal: AbortSignal;
+    cancel(): void;
+}>;
+export type SessionDeadlineFactoryV2 = (timeoutMs: number, phase: SessionDeadlinePhaseV2) => SessionDeadlineHandleV2;
+export type SessionDeadlinesV2 = Readonly<{
+    establishTimeoutMs: number;
+    rekeyPrepareTimeoutMs: number;
+    rekeyCompletionTimeoutMs: number;
+    factory?: SessionDeadlineFactoryV2;
+}>;
+export type SessionConfigV2 = Readonly<{
+    role: SessionRoleV2;
+    path: PathKind;
+    channelID: string;
+    sessionContractHash: Uint8Array;
+    suite: CipherSuiteV2;
+    psk: Uint8Array;
+    maxInboundStreams: number;
+    localAdmissionBinding: Uint8Array;
+    peerAdmissionBinding: Uint8Array;
+    /** Required by admitted APIs to bind runtime limits and keys to the signed contract. */
+    sessionContract?: SessionContractV2;
+    localEndpointInstanceID: string;
+    expectedPeerEndpointInstanceID: string;
+    rpcRouter?: RpcRouter;
+    rpcServerOptions?: RpcServerOptions;
+    deadlines?: SessionDeadlinesV2;
+    idleTimeoutMs?: number;
+    closeTimeoutMs?: number;
+    runtime: SessionProtocolRuntimeV2;
+}>;
+export type SessionProtocolRuntimeV2 = Readonly<{
+    entropy(length: number): Uint8Array;
+    monotonicMilliseconds(): number;
+}>;
+export declare class SessionV2Error extends Error {
+    readonly code: "aborted" | "closed" | "going_away" | "handshake" | "open_rejected" | "protocol" | "resource_exhausted" | "timeout";
+    constructor(code: "aborted" | "closed" | "going_away" | "handshake" | "open_rejected" | "protocol" | "resource_exhausted" | "timeout", message: string);
+}
+type HandshakeMaterial = Readonly<{
+    h3: Uint8Array;
+    sessionPRK: Uint8Array;
+    selectedFeatures: number;
+}>;
+export declare function establishSessionV2(carrier: CarrierSessionV2, config: SessionConfigV2, options?: OperationOptionsV2): Promise<SessionV2>;
+export declare class SessionV2 implements SessionV2Contract {
+    private readonly carrier;
+    private readonly control;
+    private readonly controlReader;
+    private readonly config;
+    readonly path: PathKind;
+    readonly endpointInstanceId: string | undefined;
+    readonly rpc: RpcClient;
+    readonly termination: Promise<SessionTerminationV2>;
+    readonly unreliableMessages: UnreliableMessageChannelV2 | undefined;
+    terminalError: Error | undefined;
+    private readonly role;
+    private readonly sendDirection;
+    private readonly receiveDirection;
+    private readonly h3;
+    private readonly sendRoots;
+    private readonly receiveRoots;
+    private sendEpoch;
+    private receiveEpoch;
+    private controlSendEpoch;
+    private controlSendSequence;
+    private controlReceiveEpoch;
+    private controlReceiveSequence;
+    private controlWriteTail;
+    private nextLogicalID;
+    private receivedGoAway;
+    private receivedGoAwayLastAccepted;
+    private receivedGoAwayReason;
+    private sentGoAway;
+    private sentGoAwayLastAccepted;
+    private sentGoAwayReason;
+    private closePromise;
+    private lifecycle;
+    private sentSessionClose;
+    private sessionCloseCommitted;
+    private readonly peerSessionClose;
+    private readonly streams;
+    private readonly peerLedger;
+    private readonly outboundLedger;
+    private readonly incoming;
+    private readonly outboundPermits;
+    private readonly inboundPermits;
+    private readonly pings;
+    private nextPing;
+    private readonly rpcActivation;
+    private rpcStreamPromise;
+    private rpcServing;
+    private rekeyTail;
+    private nextTransition;
+    private receiveTransition;
+    private pendingSessionRekey;
+    private lastSessionRekeyACK;
+    private preparingSendEpoch;
+    private pendingReceiveEpoch;
+    private openFrozen;
+    private openGate;
+    private outboundFrontierChanged;
+    private activeInboundResponders;
+    private localResponderFrozen;
+    private peerResponderFrozen;
+    private responderChanged;
+    private idleWatchdogStarted;
+    private idleTimer;
+    private readonly terminationState;
+    constructor(carrier: CarrierSessionV2, control: CarrierStreamV2, controlReader: ExactReader, config: SessionConfigV2, material: HandshakeMaterial);
+    openStream(kind: string, options?: InternalStreamOpenOptionsV2): Promise<ByteStreamV2>;
+    acceptStream(options?: OperationOptionsV2): Promise<IncomingStreamV2>;
+    probeLiveness(options?: OperationOptionsV2): Promise<number>;
+    rekey(options?: OperationOptionsV2): Promise<void>;
+    close(): Promise<void>;
+    start(): void;
+    rootForSend(epoch: number): EpochRootsV2;
+    rootForReceive(epoch: number): EpochRootsV2;
+    hasReceiveRoots(epoch: number): boolean;
+    installReceiveRoots(epoch: number, roots: EpochRootsV2): void;
+    transcriptHash(): Uint8Array;
+    receiveDirectionValue(): DirectionV2;
+    sendStreamRecord(stream: EncryptedStreamV2, type: InnerTypeV2, payload: Uint8Array, signal?: AbortSignal): Promise<void>;
+    readStreamRecord(stream: EncryptedStreamV2): Promise<Readonly<{
+        type: InnerTypeV2;
+        payload: Uint8Array;
+        header: RecordHeaderV2;
+    }>>;
+    localReset(stream: EncryptedStreamV2, error: Error): Promise<void>;
+    releaseStream(stream: EncryptedStreamV2): void;
+    private openLogicalStream;
+    private ensureRPCStream;
+    private acceptCarrierLoop;
+    private acceptCarrierStream;
+    private acceptCarrierStreamAfterFSS2;
+    private resetInboundBeforeDelivery;
+    private sendControl;
+    private readControl;
+    private controlLoop;
+    private closeOnce;
+    waitTermination(): Promise<SessionTerminationV2>;
+    private rekeyOnce;
+    private receiveSessionRekey;
+    private enterInboundResponder;
+    private leaveInboundResponder;
+    private freezeInboundResponders;
+    private unfreezeInboundResponders;
+    private notifyResponderChanged;
+    private receiveSessionRekeyBeforeDeadline;
+    private receiveSessionRekeyACK;
+    private waitOpenGate;
+    resolveOutboundOpen(id: bigint): void;
+    private waitOutboundFrontier;
+    private commitOutboundReset;
+    private commitLocalReset;
+    private notifyOutboundFrontierChanged;
+    private isLocalLogicalID;
+    private localOpenHighWatermark;
+    private validGoAwayBoundary;
+    private sendGoAway;
+    private receiveGoAway;
+    private localOpeningAllowedAfterGoAway;
+    private acceptsPeerStreamAfterGoAway;
+    private cleanupEpochRoots;
+    streamEpochStateChanged(): void;
+    private cleanupRootMap;
+    private wipeAllRoots;
+    private startIdleWatchdog;
+    private markAuthenticatedActivity;
+    private fail;
+    private assertOpen;
+    private beginClosing;
+}
+declare class EncryptedStreamV2 implements ByteStreamV2 {
+    readonly session: SessionV2;
+    readonly carrier: CarrierStreamV2;
+    readonly id: bigint;
+    readonly kind: string;
+    sendEpoch: number;
+    receiveEpoch: number;
+    private readonly permitRelease;
+    readonly reader: ExactReader;
+    readonly opened: Readonly<{
+        promise: Promise<void>;
+        resolve: (value: void | PromiseLike<void>) => void;
+        reject: (reason?: unknown) => void;
+        readonly settled: boolean;
+    }>;
+    readonly data: ByteQueue;
+    terminalError: Error | undefined;
+    sendSequence: bigint;
+    receiveSequence: bigint;
+    priorACK: Readonly<{
+        epoch: number;
+        sequence: bigint;
+    }> | undefined;
+    private sendTail;
+    private localFIN;
+    private remoteFIN;
+    private pumpStarted;
+    private permitReleased;
+    private pendingSendRekey;
+    private lastSendRekeyACK;
+    private receiveRekey;
+    constructor(session: SessionV2, carrier: CarrierStreamV2, id: bigint, kind: string, sendEpoch: number, receiveEpoch: number, permitRelease: () => void, reader?: ExactReader);
+    read(options?: OperationOptionsV2): Promise<Uint8Array | null>;
+    write(payload: Uint8Array, options?: OperationOptionsV2): Promise<number>;
+    closeWrite(): Promise<void>;
+    reset(): Promise<void>;
+    close(): Promise<void>;
+    send(type: InnerTypeV2, payload: Uint8Array, signal?: AbortSignal): Promise<void>;
+    canRekeySend(): boolean;
+    startSendRekey(transition: bigint, epoch: number): Readonly<{
+        armed: Deferred<void>;
+        done: Deferred<void>;
+    }>;
+    waitReceiveRekey(transition: bigint, epoch: number, signal?: AbortSignal): Promise<void>;
+    publishReceiveRekey(transition: bigint, epoch: number): void;
+    startPump(): void;
+    markOpen(): void;
+    markTerminal(error: Error): boolean;
+    peerReset(error: Error): void;
+    abort(error?: Error): void;
+    releasePermit(): void;
+    private pump;
+    private openedHash;
+    setOpenHash(value: Uint8Array): void;
+    private enqueueSend;
+    private waitSendRekey;
+    private receiveStreamKeyUpdate;
+    private receiveStreamKeyUpdateACK;
+    sendEpochsInUse(): readonly number[];
+    receiveEpochsInUse(): readonly number[];
+    private releaseIfClean;
+}
+declare class ExactReader {
+    private readonly stream;
+    private chunks;
+    private offset;
+    private bytes;
+    constructor(stream: Pick<CarrierStreamV2, "read">);
+    readExactly(length: number, signal?: AbortSignal): Promise<Uint8Array>;
+}
+declare class ByteQueue {
+    private readonly limit;
+    private readonly chunks;
+    private head;
+    private bytes;
+    private closed;
+    private error;
+    private readonly waiters;
+    constructor(limit: number);
+    push(chunk: Uint8Array): void;
+    close(): void;
+    fail(error: Error): void;
+    read(signal?: AbortSignal): Promise<Uint8Array | null>;
+    private wake;
+}
+type Deferred<T> = Readonly<{
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+    readonly settled: boolean;
+}>;
+export {};