@floegence/flowersec-core 2.3.6 → 2.3.7

package/dist/node/acceptor.d.ts

@@ -1,17 +1,7 @@
-import { type Artifact } from "../public/artifact.js";
 import { type IncomingStream, type JsonValue, type OperationOptions, type Session } from "../public/contract.js";
-export declare class RuntimeAuthorizationRequest {
-    readonly lookupKey: string;
-    private readonly requestBrand;
-    private constructor();
-}
-export type AuthorizationDecision = Readonly<{
-    decision: "allow";
-    artifact: Artifact;
-}> | Readonly<{
-    decision: "reject" | "retry";
-    reason: string;
-}>;
+import { type DirectAuthorizationDecision, type RuntimeAuthorizationRequest } from "./controlplane.js";
+export type { RuntimeAuthorizationRequest } from "./controlplane.js";
+export type AuthorizationDecision = DirectAuthorizationDecision;
 export type RPCHandlerResult = Readonly<{
     payload: JsonValue;
 }> | Readonly<{
@@ -23,6 +13,9 @@ export type RPCHandlerResult = Readonly<{
 export type RPCHandler = (payload: JsonValue, request: Readonly<{
     typeId: number;
 }>) => Promise<RPCHandlerResult>;
+export type NotificationHandler = (payload: JsonValue, request: Readonly<{
+    typeId: number;
+}>) => Promise<void> | void;
 export type StreamHandler = (incoming: IncomingStream, options: OperationOptions) => Promise<void>;
 export type SessionHandlerOptions = Readonly<{
     maxConcurrentStreams?: number;
@@ -34,16 +27,35 @@ export declare class SessionHandlersError extends Error {
 export declare class SessionHandlers {
     constructor(options?: SessionHandlerOptions);
     handleRPC(typeId: number, handler: RPCHandler): void;
+    handleNotification(typeId: number, handler: NotificationHandler): void;
     handleStream(kind: string, handler: StreamHandler): void;
 }
-export type AcceptorOptions = Readonly<{
+export type AcceptorListener = Readonly<{
+    carrier: "websocket";
+    path: "direct";
+    host: string;
+    port: number;
+    tls?: Readonly<{
+        certificate: string;
+        privateKey: string;
+    }>;
+    allowedOrigins: readonly string[];
+}> | Readonly<{
+    carrier: "raw_quic";
+    path: "direct";
     host: string;
     port: number;
-    path: string;
-    certificate: string;
-    privateKey: string;
+    tls: Readonly<{
+        certificate: string;
+        privateKey: string;
+    }>;
+}>;
+export type AcceptorOptions = Readonly<{
+    listeners: readonly AcceptorListener[];
     maxInboundStreams: number;
+    cleanupTimeoutMs?: number;
     authorize(request: RuntimeAuthorizationRequest, options: OperationOptions): Promise<AuthorizationDecision>;
+    release?(leaseId: string): Promise<void> | void;
     resolveHandlers?(request: RuntimeAuthorizationRequest, options: OperationOptions): Promise<SessionHandlers> | SessionHandlers;
 }>;
 export declare class AcceptedSession {
@@ -54,10 +66,10 @@ export declare class AcceptedSession {
 }
 export declare class Acceptor {
     private constructor();
-    address(): Readonly<{
+    addresses(): readonly Readonly<{
         host: string;
         port: number;
-    }>;
+    }>[];
     accept(operation?: OperationOptions): Promise<AcceptedSession>;
     close(): Promise<void>;
 }

package/dist/node/acceptor.js

@@ -1,21 +1,17 @@
-import { sha256 } from "@noble/hashes/sha256";
 import { RpcRouter } from "../rpc/server.js";
-import { acceptNativeSessionV2 } from "../connector/sessionAcceptor.js";
+import { acceptReceivedSessionV2, receiveSessionAdmissionV2, rejectSessionAdmissionV2, } from "../connector/sessionAcceptor.js";
 import { nodeSessionRuntimeV2 } from "./sessionRuntime.js";
-import { startNodeWebTransportServerV2, } from "./webTransportServer.js";
+import { startNodeWebSocketServer, } from "./webSocketServer.js";
+import { createNativeRawQuicDriver } from "./nativeTransportAddon.js";
+import { startNodeRawQuicServer, } from "./rawQuicServer.js";
 import { unwrapArtifact } from "../public/artifact.js";
 import { SessionError, } from "../public/contract.js";
 import { projectSessionV2 } from "../v2/publicSession.js";
-import { base64urlEncode } from "../utils/base64url.js";
+import { runtimeAuthorizationRequestFromDecoded, } from "./controlplane.js";
 const DEFAULT_MAX_CONCURRENT_STREAMS = 64;
 const MAX_CONCURRENT_STREAMS = 128;
+const DEFAULT_CLEANUP_TIMEOUT_MS = 2_000;
 const encoder = new TextEncoder();
-export class RuntimeAuthorizationRequest {
-    lookupKey;
-    constructor(lookupKey) {
-        this.lookupKey = lookupKey;
-    }
-}
 export class SessionHandlersError extends Error {
     code;
     constructor(code) {
@@ -27,28 +23,51 @@ export class SessionHandlersError extends Error {
 export class SessionHandlers {
     constructor(options = {}) {
         const maximum = options.maxConcurrentStreams ?? DEFAULT_MAX_CONCURRENT_STREAMS;
-        if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > MAX_CONCURRENT_STREAMS) {
+        if (!Number.isSafeInteger(maximum) ||
+            maximum < 1 ||
+            maximum > MAX_CONCURRENT_STREAMS) {
             throw new SessionHandlersError("invalid_handler");
         }
         sessionHandlerStates.set(this, {
             maxConcurrentStreams: maximum,
             rpc: new Map(),
+            notifications: new Map(),
             streams: new Map(),
             frozen: false,
         });
     }
     handleRPC(typeId, handler) {
         const state = mutableHandlerState(this);
-        if (!Number.isSafeInteger(typeId) || typeId < 1 || typeId > 0xffff_ffff || typeof handler !== "function") {
+        if (!Number.isSafeInteger(typeId) ||
+            typeId < 1 ||
+            typeId > 0xffff_ffff ||
+            typeof handler !== "function") {
             throw new SessionHandlersError("invalid_handler");
         }
         if (state.rpc.has(typeId))
             throw new SessionHandlersError("already_registered");
+        if (state.notifications.has(typeId))
+            throw new SessionHandlersError("already_registered");
         state.rpc.set(typeId, handler);
     }
+    handleNotification(typeId, handler) {
+        const state = mutableHandlerState(this);
+        if (!Number.isSafeInteger(typeId) ||
+            typeId < 1 ||
+            typeId > 0xffff_ffff ||
+            typeof handler !== "function") {
+            throw new SessionHandlersError("invalid_handler");
+        }
+        if (state.rpc.has(typeId) || state.notifications.has(typeId))
+            throw new SessionHandlersError("already_registered");
+        state.notifications.set(typeId, handler);
+    }
     handleStream(kind, handler) {
         const state = mutableHandlerState(this);
-        if (kind.length < 1 || encoder.encode(kind).length > 255 || kind === "flowersec.rpc.v2" || typeof handler !== "function") {
+        if (kind.length < 1 ||
+            encoder.encode(kind).length > 255 ||
+            kind === "flowersec.rpc.v2" ||
+            typeof handler !== "function") {
             throw new SessionHandlersError("invalid_handler");
         }
         if (state.streams.has(kind))
@@ -76,11 +95,39 @@ function freezeHandlers(handlers, router) {
             return { payload: result.payload };
         });
     }
+    for (const [typeId, handler] of state.notifications) {
+        router.onNotify(typeId, (payload) => {
+            void Promise.resolve(handler(payload, Object.freeze({ typeId }))).catch(() => undefined);
+        });
+    }
     return Object.freeze({
         maxConcurrentStreams: state.maxConcurrentStreams,
         streams: new Map(state.streams),
     });
 }
+/** @internal */
+export function freezeSessionHandlersForConnector(handlers) {
+    const router = new RpcRouter();
+    freezeHandlers(handlers, router);
+    return router;
+}
+/** @internal */
+export function registerSessionStreamsAtomically(handlers, entries) {
+    const state = mutableHandlerState(handlers);
+    const pending = new Set();
+    for (const [kind, handler] of entries) {
+        if (kind.length < 1 ||
+            encoder.encode(kind).length > 255 ||
+            kind === "flowersec.rpc.v2" ||
+            typeof handler !== "function")
+            throw new SessionHandlersError("invalid_handler");
+        if (state.streams.has(kind) || pending.has(kind))
+            throw new SessionHandlersError("already_registered");
+        pending.add(kind);
+    }
+    for (const [kind, handler] of entries)
+        state.streams.set(kind, handler);
+}
 export class AcceptedSession {
     constructor() { }
     get session() {
@@ -95,32 +142,44 @@ export class AcceptedSession {
                     throw new SessionError("canceled");
                 const incoming = await this.session.acceptStream(options);
                 const handler = state.handlers.streams.get(incoming.kind);
-                if (handler === undefined || active.size >= state.handlers.maxConcurrentStreams) {
+                if (handler === undefined ||
+                    active.size >= state.handlers.maxConcurrentStreams) {
                     await incoming.stream.reset();
                     continue;
                 }
                 const task = (async () => {
                     try {
                         await handler(incoming, options);
+                        await incoming.stream.closeWrite();
                     }
                     catch {
                         await incoming.stream.reset().catch(() => undefined);
                     }
-                    finally {
-                        await incoming.stream.close().catch(() => undefined);
-                    }
-                })()
-                    .finally(() => active.delete(task));
+                })().finally(() => active.delete(task));
                 active.add(task);
             }
         }
         finally {
-            await this.session.close().catch(() => undefined);
+            await this.close().catch(() => undefined);
             await Promise.allSettled(active);
         }
     }
     async close() {
-        await this.session.close();
+        const state = acceptedSessionState(this);
+        if (state.closePromise === undefined) {
+            state.closePromise = (async () => {
+                try {
+                    await state.session.close();
+                }
+                finally {
+                    if (state.release !== undefined && state.releasePromise === undefined) {
+                        state.releasePromise = Promise.resolve().then(() => state.release());
+                    }
+                    await state.releasePromise;
+                }
+            })();
+        }
+        await state.closePromise;
     }
 }
 const acceptedSessionStates = new WeakMap();
@@ -130,49 +189,174 @@ function acceptedSessionState(accepted) {
         throw new SessionError("operation_failed");
     return state;
 }
-function createAcceptedSession(session, handlers) {
+function createAcceptedSession(session, handlers, release) {
     const accepted = new AcceptedSession();
-    acceptedSessionStates.set(accepted, { session, handlers });
+    const state = { session, handlers };
+    if (release !== undefined)
+        state.release = release;
+    acceptedSessionStates.set(accepted, state);
     return Object.freeze(accepted);
 }
 export class Acceptor {
     constructor() { }
-    address() {
-        return acceptorState(this).server.address();
+    addresses() {
+        return acceptorState(this).listeners.map((listener) => listener.address());
     }
     async accept(operation = {}) {
         const state = acceptorState(this);
-        const carrier = await state.server.accept(operation);
+        state.start();
+        return await state.accepted.shift(operation.signal);
+    }
+    async close() {
+        const state = acceptorState(this);
+        state.abort.abort();
+        state.accepted.close();
+        await Promise.all(state.listeners.map(async (listener) => await listener.close()));
+        await boundedCleanup(state.tasks, state.cleanupTimeoutMs);
+        state.tasks.clear();
+    }
+}
+async function releaseLease(state, leaseId) {
+    if (leaseId === undefined || state.options.release === undefined)
+        return;
+    await state.options.release(leaseId);
+}
+async function authorizeCarrier(state, carrier) {
+    const received = await receiveSessionAdmissionV2(carrier, state.abort.signal);
+    const decoded = received.decoded;
+    const request = runtimeAuthorizationRequestFromDecoded(decoded);
+    const decision = await abortableCallback(state.options.authorize(request, { signal: state.abort.signal }), state.abort.signal);
+    if (decision.decision !== "allow") {
+        return await rejectSessionAdmissionV2(received, {
+            accepted: false,
+            status: decision.decision === "retry" ? 2 : 1,
+            reason: decision.reason,
+        }, state.abort.signal);
+    }
+    const leaseId = "leaseId" in decision && typeof decision.leaseId === "string"
+        ? decision.leaseId
+        : undefined;
+    try {
         const router = new RpcRouter();
-        let handlers;
-        const internal = await acceptNativeSessionV2(carrier, async (decoded, signal) => {
-            const request = runtimeAuthorizationRequest(decoded);
-            const decision = await state.options.authorize(request, signal === undefined ? {} : { signal });
-            if (decision.decision !== "allow") {
-                return {
-                    accepted: false,
-                    status: decision.decision === "retry" ? 2 : 1,
-                    reason: decision.reason,
-                };
-            }
-            const registry = state.options.resolveHandlers === undefined
-                ? new SessionHandlers()
-                : await state.options.resolveHandlers(request, signal === undefined ? {} : { signal });
-            handlers = freezeHandlers(registry, router);
-            return { accepted: true, artifact: unwrapArtifact(decision.artifact) };
-        }, {
-            runtime: nodeSessionRuntimeV2,
-            rpcRouter: router,
-            ...(operation.signal === undefined ? {} : { signal: operation.signal }),
-        });
-        if (handlers === undefined) {
-            await internal.close().catch(() => undefined);
+        const registry = state.options.resolveHandlers === undefined
+            ? new SessionHandlers()
+            : await abortableCallback(Promise.resolve(state.options.resolveHandlers(request, {
+                signal: state.abort.signal,
+            })), state.abort.signal);
+        const leg = {
+            received,
+            artifact: unwrapArtifact(decision.artifact),
+            handlers: freezeHandlers(registry, router),
+            router,
+        };
+        if (leaseId !== undefined)
+            leg.leaseId = leaseId;
+        return leg;
+    }
+    catch (error) {
+        await releaseLease(state, leaseId).catch(() => undefined);
+        throw error;
+    }
+}
+async function establishDirect(leg, signal, release) {
+    const internal = await acceptReceivedSessionV2(leg.received, leg.artifact, {
+        runtime: nodeSessionRuntimeV2,
+        rpcRouter: leg.router,
+        role: "server",
+        signal,
+    });
+    return createAcceptedSession(projectSessionV2(internal), leg.handlers, release);
+}
+async function processCarrier(state, carrier) {
+    const leg = await authorizeCarrier(state, carrier);
+    if (leg === undefined)
+        return;
+    try {
+        if (leg.received.decoded.request.pathKind !== "direct" ||
+            leg.artifact.path.kind !== "direct") {
+            await leg.received.carrier.close().catch(() => undefined);
             throw new SessionError("operation_failed");
         }
-        return createAcceptedSession(projectSessionV2(internal), handlers);
+        state.accepted.push(await establishDirect(leg, state.abort.signal, leg.leaseId === undefined ? undefined : () => releaseLease(state, leg.leaseId)));
     }
-    async close() {
-        await acceptorState(this).server.close();
+    catch (error) {
+        await releaseLease(state, leg.leaseId).catch(() => undefined);
+        throw error;
+    }
+}
+async function runAcceptLoop(state) {
+    while (!state.abort.signal.aborted) {
+        try {
+            const carrier = await state.accept({ signal: state.abort.signal });
+            const task = processCarrier(state, carrier)
+                .catch(async () => {
+                await carrier.close().catch(() => undefined);
+            })
+                .finally(() => state.tasks.delete(task));
+            state.tasks.add(task);
+        }
+        catch (error) {
+            if (!state.abort.signal.aborted)
+                state.accepted.fail(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+    }
+}
+class AcceptedQueue {
+    values = [];
+    waiters = new Set();
+    failure;
+    push(value) {
+        if (this.failure !== undefined) {
+            void value.close();
+            return;
+        }
+        const waiter = this.waiters.values().next().value;
+        if (waiter === undefined)
+            this.values.push(value);
+        else {
+            this.waiters.delete(waiter);
+            waiter.resolve(value);
+        }
+    }
+    async shift(signal) {
+        if (signal?.aborted === true)
+            throw new SessionError("canceled");
+        const value = this.values.shift();
+        if (value !== undefined)
+            return value;
+        if (this.failure !== undefined)
+            throw this.failure;
+        return await new Promise((resolve, reject) => {
+            const waiter = {
+                resolve: (session) => {
+                    cleanup();
+                    resolve(session);
+                },
+                reject: (error) => {
+                    cleanup();
+                    reject(error);
+                },
+            };
+            const abort = () => {
+                this.waiters.delete(waiter);
+                reject(new SessionError("canceled"));
+            };
+            const cleanup = () => signal?.removeEventListener("abort", abort);
+            this.waiters.add(waiter);
+            signal?.addEventListener("abort", abort, { once: true });
+        });
+    }
+    fail(error) {
+        if (this.failure !== undefined)
+            return;
+        this.failure = error;
+        for (const waiter of this.waiters)
+            waiter.reject(error);
+        this.waiters.clear();
+    }
+    close() {
+        this.fail(new SessionError("closed"));
     }
 }
 const acceptorStates = new WeakMap();
@@ -183,35 +367,132 @@ function acceptorState(acceptor) {
     return state;
 }
 export async function createAcceptor(options) {
-    if (!Number.isSafeInteger(options.maxInboundStreams) || options.maxInboundStreams < 1 || options.maxInboundStreams > 128) {
+    if (!Number.isSafeInteger(options.maxInboundStreams) ||
+        options.maxInboundStreams < 1 ||
+        options.maxInboundStreams > 128 ||
+        options.listeners.length === 0) {
         throw new TypeError("invalid Flowersec Acceptor options");
     }
-    const server = await startNodeWebTransportServerV2({
-        host: options.host,
-        port: options.port,
-        path: options.path,
-        certificate: options.certificate,
-        privateKey: options.privateKey,
-        carrierPath: "direct",
-        inboundBidirectionalStreamCapacity: options.maxInboundStreams + 2,
-    });
+    const cleanupTimeoutMs = options.cleanupTimeoutMs ?? DEFAULT_CLEANUP_TIMEOUT_MS;
+    if (!Number.isSafeInteger(cleanupTimeoutMs) || cleanupTimeoutMs < 1 || cleanupTimeoutMs > 60_000) {
+        throw new TypeError("invalid Flowersec Acceptor cleanup timeout");
+    }
+    if (options.listeners.some((listener) => listener.path !== "direct")) {
+        throw new TypeError("Flowersec Acceptor listeners must use the direct path");
+    }
+    const listeners = [];
+    let rawQuicDriver;
+    try {
+        for (const listener of options.listeners) {
+            if (listener.carrier === "websocket") {
+                listeners.push(await startNodeWebSocketServer({
+                    ...listener,
+                    inboundBidirectionalStreamCapacity: options.maxInboundStreams + 2,
+                }));
+            }
+            else {
+                rawQuicDriver ??= createNativeRawQuicDriver();
+                listeners.push(await startNodeRawQuicServer(rawQuicDriver, {
+                    ...listener,
+                    inboundBidirectionalStreamCapacity: options.maxInboundStreams + 2,
+                }));
+            }
+        }
+    }
+    catch (error) {
+        await Promise.allSettled(listeners.map(async (listener) => await listener.close()));
+        throw error;
+    }
+    let cursor = 0;
+    const accept = async (operation) => {
+        if (listeners.length === 1)
+            return await listeners[0].accept(operation);
+        const controller = new AbortController();
+        const abort = () => controller.abort(operation.signal?.reason);
+        operation.signal?.addEventListener("abort", abort, { once: true });
+        try {
+            return await Promise.any(listeners.map(async (listener, index) => {
+                const selected = listeners[(index + cursor) % listeners.length];
+                return await selected.accept({ signal: controller.signal });
+            })).finally(() => {
+                cursor = (cursor + 1) % listeners.length;
+                controller.abort();
+            });
+        }
+        finally {
+            operation.signal?.removeEventListener("abort", abort);
+        }
+    };
     const acceptor = new Acceptor();
-    acceptorStates.set(acceptor, { server, options });
+    const accepted = new AcceptedQueue();
+    const abort = new AbortController();
+    const tasks = new Set();
+    let started = false;
+    const state = {
+        listeners,
+        options,
+        accept,
+        accepted,
+        abort,
+        tasks,
+        cleanupTimeoutMs,
+        start() {
+            if (started)
+                return;
+            started = true;
+            const task = runAcceptLoop(state).finally(() => tasks.delete(task));
+            tasks.add(task);
+        },
+    };
+    acceptorStates.set(acceptor, state);
     return Object.freeze(acceptor);
 }
-function runtimeAuthorizationRequest(decoded) {
-    const credential = decoded.request.pathKind === "direct"
-        ? decoded.request.routing_token
-        : decoded.request.attach_token;
-    const lookupKey = base64urlEncode(sha256(encoder.encode(credential)));
-    return new RuntimeAuthorizationRequest(lookupKey);
+async function boundedCleanup(tasks, timeoutMs) {
+    await Promise.race([
+        Promise.allSettled([...tasks]).then(() => undefined),
+        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+}
+async function abortableCallback(promise, signal) {
+    if (signal.aborted)
+        throw signal.reason instanceof Error ? signal.reason : new SessionError("closed");
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => signal.removeEventListener("abort", abort);
+        const abort = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(signal.reason instanceof Error ? signal.reason : new SessionError("closed"));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        void promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        });
+    });
 }
 function validRPCError(error) {
-    if (!Number.isSafeInteger(error.code) || error.code < 1 || error.code > 0xffff_ffff) {
+    if (!Number.isSafeInteger(error.code) ||
+        error.code < 1 ||
+        error.code > 0xffff_ffff) {
         return { code: 500, message: "handler failed" };
     }
-    if (error.message !== undefined && encoder.encode(error.message).length > 1024) {
+    if (error.message !== undefined &&
+        encoder.encode(error.message).length > 1024) {
         return { code: 500, message: "handler failed" };
     }
-    return error.message === undefined ? { code: error.code } : { code: error.code, message: error.message };
+    return error.message === undefined
+        ? { code: error.code }
+        : { code: error.code, message: error.message };
 }

package/dist/node/connectSession.d.ts

@@ -1,15 +1,16 @@
 import type { ArtifactLease } from "../public/artifactLease.js";
 import type { Session } from "../public/contract.js";
 import { type ArtifactSource, type ConnectionController } from "../connectionController.js";
+import { type SessionHandlers } from "./acceptor.js";
 export type SessionTLSOptions = Readonly<{
     ca?: string | Uint8Array;
-    serverCertificateHash?: Uint8Array;
 }>;
 export type SessionOptions = Readonly<{
     origin: string;
     signal?: AbortSignal;
     connectTimeoutMs?: number;
     tls?: SessionTLSOptions;
+    handlers?: SessionHandlers;
 }>;
 export type ConnectionControllerOptions = Readonly<{
     origin: string;