@floegence/flowersec-core 0.22.1 → 0.24.0

package/README.md

@@ -1,8 +1,6 @@
 # @floegence/flowersec-core
 
-Flowersec core TypeScript library for the complete portable Flowersec client/server contract in Node.js, plus the browser and Service Worker runtime owned by TypeScript.
-
-Status: experimental; not audited.
+The TypeScript SDK for Flowersec end-to-end encrypted direct and tunneled sessions. It implements the portable Node.js client and endpoint contract plus the browser and Service Worker runtime owned by TypeScript.
 
 ## Install
 
@@ -10,73 +8,27 @@ Status: experimental; not audited.
 npm install @floegence/flowersec-core
 ```
 
-## Recommended usage
-
-Browser:
-
-```ts
-import { connectBrowser } from "@floegence/flowersec-core/browser";
-import { requestConnectArtifact } from "@floegence/flowersec-core/controlplane";
-
-const artifact = await requestConnectArtifact({
-  endpointId: "env_demo",
-});
-
-const client = await connectBrowser(artifact);
-await client.ping();
-client.close();
-```
-
-Node.js:
-
-```ts
-import { connectNode, createNodeReconnectConfig } from "@floegence/flowersec-core/node";
-import { requestConnectArtifact } from "@floegence/flowersec-core/controlplane";
-import { createControlplaneArtifactSource } from "@floegence/flowersec-core/reconnect";
-
-const artifact = await requestConnectArtifact({
-  baseUrl: "https://your-app.example/api/flowersec",
-  endpointId: "env_demo",
-});
-
-const client = await connectNode(artifact, {
-  origin: "https://your-app.example",
-});
-await client.ping();
-const rttMs = await client.probeLiveness();
-client.close();
-
-const reconnectConfig = createNodeReconnectConfig({
-  source: createControlplaneArtifactSource({
-    baseUrl: "https://your-app.example/api/flowersec",
-    endpointId: "env_demo",
-  }),
-  connect: {
-    origin: "https://your-app.example",
-  },
-});
-```
+The package is ESM-only and exposes environment-specific entrypoints for browser and Node.js applications.
 
-Browser `requestConnectArtifact(...)`, `requestEntryConnectArtifact(...)`, and `ControlplaneRequestError` remain available from `@floegence/flowersec-core/browser` as stable aliases.
+## Cookbook
 
-High-level connects use `RequireTLS` by default. `AllowPlaintextForLoopback` permits only literal loopback
-targets without DNS resolution. Deliberate non-loopback `ws://` connections must use
-`createNetworkPlaintextPolicy(...)` with exact canonical IP literals and
-`PlaintextRiskAcceptance.acceptPreE2ECredentialExposure`. The unrestricted `AllowPlaintext` preset is deprecated.
+Start with the [TypeScript cookbook](https://github.com/floegence/flowersec/tree/main/examples/ts). It contains runnable browser direct/tunnel pages, Node.js clients, the shared demo server, the Service Worker proxy runtime, and manual protocol-stack references.
 
-## Node endpoint and controlplane
+## Entrypoints
 
-`@floegence/flowersec-core/node` exports the high-level endpoint APIs for accepted direct WebSockets and server-role tunnel grants. `@floegence/flowersec-core/endpoint` provides portable session and RPC serving, while `@floegence/flowersec-core/controlplane` provides bounded artifact envelopes, FST2 tokens, issuer rotation, and channel initialization.
+- Browser client: `@floegence/flowersec-core/browser`
+- Node.js client and endpoint transport: `@floegence/flowersec-core/node`
+- Controlplane artifact helpers: `@floegence/flowersec-core/controlplane`
+- Endpoint session serving: `@floegence/flowersec-core/endpoint`
+- RPC: `@floegence/flowersec-core/rpc`
+- Reconnect: `@floegence/flowersec-core/reconnect`
+- HTTP/WebSocket proxy and browser runtime: `@floegence/flowersec-core/proxy`
+- Observability: `@floegence/flowersec-core/observability`
 
-## Proxy
+High-level WebSocket connections require TLS by default. Use `AllowPlaintextForLoopback` only for literal local development targets.
 
-`@floegence/flowersec-core/proxy` contains both portable HTTP/1 and WebSocket proxy protocols and the TypeScript-owned browser runtime. Node endpoint servers use `serveProxySession(...)`; browser applications use the Service Worker or controller bridge helpers without changing the portable stream contract.
+## Runtime Boundaries
 
-## Docs
+TypeScript owns browser and Service Worker integration. Shared tunnel, proxy gateway, and helper binaries remain Go-owned.
 
-- Frontend quickstart: `docs/FRONTEND_QUICKSTART.md`
-- Integration guide: `docs/INTEGRATION_GUIDE.md`
-- API surface contract: `docs/API_SURFACE.md`
-- Controlplane artifact fetch: `docs/CONTROLPLANE_ARTIFACT_FETCH.md`
-- Error model: `docs/ERROR_MODEL.md`
-- Migration guide: `docs/V0_20_MIGRATION.md`
+Review the shared [API contract](../docs/API_CONTRACT.md), [protocol](../docs/PROTOCOL.md), [threat model](../docs/THREAT_MODEL.md), and [error model](../docs/ERROR_MODEL.md).

package/YAMUX_ALIGNMENT.md

@@ -77,19 +77,19 @@ Source: `flowersec-ts/src/yamux/constants.ts`, `flowersec-ts/src/yamux/header.ts
 The TS Yamux implementation is exercised in real interop scenarios:
 
 - **TS client ↔ Go server (minimal Yamux over TCP)**:
-  - Test: `flowersec-ts/src/e2e/yamux_interop.test.ts` (minimal tcp mode)
-  - Go harness: `flowersec-go/internal/cmd/flowersec-yamux-harness/main.go`
+  - Test: `flowersec-go/internal/cmd/flowersec-interop` with the TypeScript JSONL harness
+  - Go reference: production `client`, `endpoint`, and Yamux-backed session APIs
   - Covers: window update race, RST handling, concurrent open/close, session close.
   - Notes: opt-in via `YAMUX_INTEROP=1` (runs Go harnesses).
   - Notes: sizes scale via `YAMUX_INTEROP_SCALE` (e.g. `2` => 20 streams / 1 MiB per stream).
   - Notes: client-initiated RST scenarios run when `YAMUX_INTEROP_CLIENT_RST=1`.
   - Notes: window-update and concurrent-open/close stress runs when `YAMUX_INTEROP_STRESS=1`.
 - **TS client ↔ Go server (full chain: E2EE + tunnel + Yamux)**:
-  - Test: `flowersec-ts/src/e2e/yamux_interop.test.ts` (full chain mode)
+  - Test: the Direct/Tunnel variants in `stability/interop_matrix.json`
   - Go harness: `flowersec-go/internal/cmd/flowersec-e2e-harness/main.go` with `-scenario`
   - Notes: reduced stream counts/payload sizes to keep end-to-end runtime bounded.
 - **Layered close/reset probes (memory + WS + full chain)**:
-  - Test: `flowersec-ts/src/e2e/yamux_interop_layers.test.ts`
+  - Test: the Go-reference smoke and stress profiles in `testdata/interop/v1/profiles.json`
   - Covers: session-close wakeup, FIN/RST delivery across SecureChannel + WebSocketBinaryTransport,
     and a full-chain FIN/RST probe on `rst_mid_write_go`.
   - Notes: gated by `YAMUX_INTEROP=1`; the full-chain probe additionally requires

package/dist/client-connect/connectCore.d.ts

@@ -23,7 +23,7 @@ export type ConnectOptionsBase = Readonly<{
     maxHandshakePayload?: number;
     /** Maximum encrypted record size on the wire (0 uses default). */
     maxRecordBytes?: number;
-    /** Maximum buffered plaintext bytes in the secure channel (0 uses default). */
+    /** Maximum queued inbound plaintext bytes in the secure channel (0 uses default). */
     maxBufferedBytes?: number;
     /** Maximum queued outbound plaintext bytes in the secure channel (default 4 MiB; 0 uses default). */
     maxOutboundBufferedBytes?: number;
@@ -39,9 +39,9 @@ export type ConnectOptionsBase = Readonly<{
     observer?: ClientObserverLike;
     /** Policy evaluated before any WebSocket network activity. */
     transportSecurityPolicy?: TransportSecurityPolicy;
-    /** Experimental scope validators keyed by scope name. */
+    /** Scope validators keyed by scope name. */
     scopeResolvers?: ConnectScopeResolverMap;
-    /** Experimental migration switch for optional scope failures. */
+    /** Explicit compatibility switch for optional scope failures. */
     relaxedOptionalScopeValidation?: boolean;
     /** Acknowledged Yamux liveness checks, or false to disable automatic checks. */
     liveness?: false | LivenessOptions;

package/dist/client-connect/connectCore.js

@@ -14,7 +14,7 @@ import { prepareChannelId } from "./contract.js";
 import { isTunnelAttachCloseReason } from "./tunnelAttachCloseReason.js";
 import { enforceTransportSecurity } from "./transportSecurity.js";
 import { maxPlaintextBytes } from "../e2ee/record.js";
-import { isYamuxResourceExhaustedError } from "../yamux/errors.js";
+import { isYamuxPingTimeoutError, isYamuxResourceExhaustedError } from "../yamux/errors.js";
 import { registerClientTermination } from "./termination.js";
 export async function connectCore(args) {
     const observer = normalizeObserver(args.opts.observer, { path: args.path });
@@ -143,12 +143,6 @@ export async function connectCore(args) {
         catch (err) {
             const reason = classifyConnectError(err);
             observer.onConnect(args.path, "fail", reason, nowSeconds() - connectStart);
-            try {
-                transport.close();
-            }
-            catch {
-                // ignore
-            }
             const code = reason === "timeout" ? "timeout" : reason === "canceled" ? "canceled" : "dial_failed";
             throw new FlowersecError({
                 path: args.path,
@@ -167,12 +161,6 @@ export async function connectCore(args) {
             catch (err) {
                 observer.onAttach("fail", "send_failed");
                 attachState = "failed";
-                try {
-                    transport.close();
-                }
-                catch {
-                    // ignore
-                }
                 throw new FlowersecError({ path: args.path, stage: "attach", code: "attach_failed", message: "attach failed", cause: err });
             }
         }
@@ -202,7 +190,6 @@ export async function connectCore(args) {
         catch (err) {
             const handshakeElapsedSeconds = nowSeconds() - handshakeStart;
             const handshakeCode = classifyHandshakeError(err);
-            transport.close();
             if (args.path === "tunnel" && err instanceof WsCloseError) {
                 const reason = err.reason;
                 if (isTunnelAttachCloseReason(reason)) {
@@ -233,17 +220,20 @@ export async function connectCore(args) {
         });
         let terminationReported = false;
         let closeAll = () => {
-            try {
-                secure.close();
-            }
-            catch { /* ignore */ }
+            runSyncCleanups([() => secure.close()]);
         };
         const reportTermination = (error) => {
             if (terminationReported)
                 return;
             terminationReported = true;
-            closeAll();
-            resolveTermination({ error });
+            let terminalError = error;
+            try {
+                closeAll();
+            }
+            catch (cleanupError) {
+                terminalError = errorWithCleanup(error, cleanupError, "session termination cleanup failed");
+            }
+            resolveTermination({ error: terminalError });
         };
         const mux = new YamuxSession(conn, {
             client: true,
@@ -261,23 +251,21 @@ export async function connectCore(args) {
             }),
         });
         closeAll = () => {
-            try {
-                mux.close();
-            }
-            catch { /* ignore */ }
-            try {
-                secure.close();
-            }
-            catch { /* ignore */ }
+            runSyncCleanups([() => mux.close(), () => secure.close()]);
         };
         let rpcStream;
         try {
             rpcStream = await mux.openStream(signal === undefined ? {} : { signal });
         }
         catch (e) {
-            mux.close();
-            secure.close();
-            throw new FlowersecError({ path: args.path, stage: "yamux", code: "open_stream_failed", message: "open rpc stream failed", cause: e });
+            const cleanupError = captureSyncCleanup(() => runSyncCleanups([() => mux.close(), () => secure.close()]));
+            throw new FlowersecError({
+                path: args.path,
+                stage: "yamux",
+                code: "open_stream_failed",
+                message: "open rpc stream failed",
+                cause: causeWithCleanup(e, cleanupError, "RPC stream setup cleanup failed"),
+            });
         }
         const reader = new ByteReader(() => rpcStream.read());
         const readExactly = (n) => reader.readExactly(n);
@@ -286,20 +274,19 @@ export async function connectCore(args) {
             await writeStreamHello(write, "rpc");
         }
         catch (e) {
-            try {
-                await rpcStream.close();
-            }
-            catch {
-                // ignore
-            }
-            mux.close();
-            secure.close();
+            const cleanupError = await captureAsyncCleanup(async () => {
+                const streamCloseError = await captureAsyncCleanup(() => rpcStream.close());
+                const stackCloseError = captureSyncCleanup(() => runSyncCleanups([() => mux.close(), () => secure.close()]));
+                const combined = errorsFrom([streamCloseError, stackCloseError]);
+                if (combined != null)
+                    throw combined;
+            });
             throw new FlowersecError({
                 path: args.path,
                 stage: "rpc",
                 code: "stream_hello_failed",
                 message: "rpc stream hello failed",
-                cause: e,
+                cause: causeWithCleanup(e, cleanupError, "RPC bootstrap cleanup failed"),
             });
         }
         const rpc = new RpcClient(readExactly, write, { observer, onTerminal: reportTermination });
@@ -316,22 +303,13 @@ export async function connectCore(args) {
                 return await mux.probeLiveness(liveness.timeoutMs);
             }
             catch (e) {
-                if (String(e?.message).includes("ping timeout")) {
+                const timedOut = isYamuxPingTimeoutError(e);
+                if (timedOut) {
                     emitObserverDiagnostic(args.opts.observer, { path: args.path, stage: "yamux", code_domain: "event", code: "liveness_timeout", result: "fail" });
                 }
-                try {
-                    rpc.close();
-                }
-                catch { /* ignore */ }
-                try {
-                    mux.close();
-                }
-                catch { /* ignore */ }
-                try {
-                    secure.close();
-                }
-                catch { /* ignore */ }
-                throw new FlowersecError({ path: args.path, stage: "yamux", code: "ping_failed", message: "liveness probe failed", cause: e });
+                const error = new FlowersecError({ path: args.path, stage: "yamux", code: timedOut ? "timeout" : "ping_failed", message: "liveness probe failed", cause: e });
+                reportTermination(error);
+                throw error;
             }
         };
         let livenessTimer;
@@ -344,24 +322,7 @@ export async function connectCore(args) {
         };
         closeAll = () => {
             stopLiveness();
-            try {
-                rpc.close();
-            }
-            catch {
-                // ignore
-            }
-            try {
-                mux.close();
-            }
-            catch {
-                // ignore
-            }
-            try {
-                secure.close();
-            }
-            catch {
-                // ignore
-            }
+            runSyncCleanups([() => rpc.close(), () => mux.close(), () => secure.close()]);
         };
         if (liveness.intervalMs > 0) {
             livenessTimer = setInterval(() => {
@@ -385,10 +346,19 @@ export async function connectCore(args) {
             mux,
             rpc,
             ping,
+            rekey: async () => {
+                try {
+                    await secure.rekeyNow();
+                }
+                catch (error) {
+                    throw new FlowersecError({ path: args.path, stage: "secure", code: "rekey_failed", message: "rekey failed", cause: error });
+                }
+            },
             probeLiveness,
             openStream: async (kind, opts = {}) => {
-                if (kind == null || kind === "")
-                    throw new FlowersecError({ path: args.path, stage: "validate", code: "missing_stream_kind", message: "missing stream kind" });
+                const streamKind = kind?.trim() ?? "";
+                if (streamKind === "")
+                    throw new FlowersecError({ path: args.path, stage: "rpc", code: "missing_stream_kind", message: "missing stream kind" });
                 if (opts.signal?.aborted) {
                     throw new FlowersecError({
                         path: args.path,
@@ -408,6 +378,7 @@ export async function connectCore(args) {
                 };
                 const signal = opts.signal;
                 let abortListener;
+                let abortReset;
                 let s;
                 try {
                     s = await mux.openStream(signal === undefined ? {} : { signal });
@@ -421,12 +392,7 @@ export async function connectCore(args) {
                 }
                 if (signal != null) {
                     abortListener = () => {
-                        try {
-                            s.reset(abortReason(signal));
-                        }
-                        catch {
-                            // ignore
-                        }
+                        abortReset ??= captureAsyncCleanup(() => Promise.resolve(s.reset(abortReason(signal))));
                     };
                     signal.addEventListener("abort", abortListener, { once: true });
                     if (signal.aborted)
@@ -435,55 +401,52 @@ export async function connectCore(args) {
                 if (signal?.aborted) {
                     if (abortListener != null)
                         signal.removeEventListener("abort", abortListener);
-                    try {
-                        await s.close();
-                    }
-                    catch {
-                        // ignore
-                    }
+                    const cleanupError = await captureAsyncCleanup(async () => {
+                        const resetError = abortReset == null ? undefined : await abortReset;
+                        const closeError = await captureAsyncCleanup(() => s.close());
+                        const combined = errorsFrom([resetError, closeError]);
+                        if (combined != null)
+                            throw combined;
+                    });
                     throw new FlowersecError({
                         path: args.path,
                         stage: "yamux",
                         code: "canceled",
                         message: "open stream aborted",
-                        cause: signal.reason,
+                        cause: causeWithCleanup(signal.reason, cleanupError, "aborted stream cleanup failed"),
                     });
                 }
                 try {
-                    await writeStreamHello((b) => s.write(b), kind);
+                    await writeStreamHello((b) => s.write(b), streamKind);
                 }
                 catch (err) {
                     if (signal?.aborted) {
                         if (abortListener != null)
                             signal.removeEventListener("abort", abortListener);
-                        try {
-                            await s.close();
-                        }
-                        catch {
-                            // ignore
-                        }
+                        const cleanupError = await captureAsyncCleanup(async () => {
+                            const resetError = abortReset == null ? undefined : await abortReset;
+                            const closeError = await captureAsyncCleanup(() => s.close());
+                            const combined = errorsFrom([resetError, closeError]);
+                            if (combined != null)
+                                throw combined;
+                        });
                         throw new FlowersecError({
                             path: args.path,
                             stage: "yamux",
                             code: "canceled",
                             message: "open stream aborted",
-                            cause: signal.reason,
+                            cause: causeWithCleanup(signal.reason, cleanupError, "aborted stream cleanup failed"),
                         });
                     }
                     if (signal != null && abortListener != null)
                         signal.removeEventListener("abort", abortListener);
-                    try {
-                        await s.close();
-                    }
-                    catch {
-                        // ignore
-                    }
+                    const cleanupError = await captureAsyncCleanup(() => s.close());
                     throw new FlowersecError({
                         path: args.path,
                         stage: "rpc",
                         code: "stream_hello_failed",
                         message: "stream hello failed",
-                        cause: err,
+                        cause: causeWithCleanup(err, cleanupError, "stream hello cleanup failed"),
                     });
                 }
                 if (signal != null && abortListener != null) {
@@ -499,14 +462,65 @@ export async function connectCore(args) {
         return client;
     }
     catch (e) {
+        const cleanupError = captureSyncCleanup(() => transport.close());
+        throw cleanupError == null ? e : errorWithCleanup(e, cleanupError, "transport cleanup failed");
+    }
+}
+function runSyncCleanups(actions) {
+    const failures = [];
+    for (const action of actions) {
         try {
-            transport.close();
+            action();
         }
-        catch {
-            // ignore
+        catch (error) {
+            failures.push(errorValue(error));
         }
-        throw e;
     }
+    if (failures.length > 0)
+        throw new AggregateError(failures, "Flowersec cleanup failed");
+}
+function captureSyncCleanup(action) {
+    try {
+        action();
+        return undefined;
+    }
+    catch (error) {
+        return error;
+    }
+}
+async function captureAsyncCleanup(action) {
+    try {
+        await action();
+        return undefined;
+    }
+    catch (error) {
+        return error;
+    }
+}
+function causeWithCleanup(primary, cleanup, message) {
+    if (cleanup === undefined)
+        return primary;
+    return new AggregateError([errorValue(primary), errorValue(cleanup)], message);
+}
+function errorWithCleanup(primary, cleanup, message) {
+    const cause = causeWithCleanup(primary, cleanup, message);
+    if (primary instanceof FlowersecError) {
+        return new FlowersecError({
+            path: primary.path,
+            stage: primary.stage,
+            code: primary.code,
+            message,
+            cause,
+        });
+    }
+    return new AggregateError([errorValue(primary), errorValue(cleanup)], message);
+}
+function errorsFrom(values) {
+    const failures = values.filter((value) => value !== undefined).map(errorValue);
+    return failures.length === 0 ? undefined : new AggregateError(failures, "Flowersec cleanup failed");
+}
+function errorValue(error) {
+    return error instanceof Error ? error : new Error(String(error));
 }
 function validateLimitObject(input, name, invalid) {
     if (input === undefined)

package/dist/client.d.ts

@@ -11,6 +11,8 @@ export type Client = Readonly<{
         signal?: AbortSignal;
     }>) => Promise<YamuxStream>;
     ping: () => Promise<void>;
+    /** Emits an authenticated rekey record and advances the E2EE send key. */
+    rekey: () => Promise<void>;
     /** Performs an acknowledged Yamux round trip and returns RTT in milliseconds. */
     probeLiveness: () => Promise<number>;
     close: () => void;

package/dist/controlplane/issuer.d.ts

@@ -1,7 +1,7 @@
 import { type TokenPayload } from "./token.js";
 export declare class IssuerKeyset {
-    private kid;
-    private signingSeed;
+    private active;
+    private readonly verificationKeys;
     constructor(kid: string, signingSeed: Uint8Array);
     static random(kid: string): IssuerKeyset;
     currentKID(): string;
@@ -9,7 +9,10 @@ export declare class IssuerKeyset {
     sign(payload: Omit<TokenPayload, "kid"> & Readonly<{
         kid?: string;
     }>): string;
+    addVerificationKey(kid: string, publicKey: Uint8Array): void;
     rotate(kid: string, signingSeed: Uint8Array): void;
+    retireVerificationKey(kid: string): void;
     exportTunnelKeyset(): Uint8Array;
     dispose(): void;
+    private requireActive;
 }