@nice-code/action 0.5.5 → 0.6.1

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Transport.types.d.ts

@@ -83,7 +83,13 @@ export interface ITransportDispatchAction<P> extends ITransportMethod_SendAction
     params: P;
 }
 export type TSendActionDataMethod = (input: ITransportMethod_SendActionData_Input) => void;
-export type TSendReturnDataMethod = (payload: TActionPayload_Any_Instance<any, any>) => void;
+export type TSendReturnDataMethod = (payload: TActionPayload_Any_Instance<any, any>, 
+/**
+ * The local/external client pair this payload is being returned over. Bidirectional transports use
+ * it to build the full route params their outgoing formatter expects (e.g. binary packing). Optional
+ * so existing return-data implementations keep type-checking.
+ */
+clients?: ITransportRouteClientParams) => void;
 export interface IActionTransportReadyData_Methods extends IActionTransportReadyData_Base {
     sendActionData: TSendActionDataMethod;
     /**

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/TransportWebSocket.types.d.ts

@@ -1,11 +1,39 @@
-import type { IActionPayload_Request_JsonObject, IActionPayload_Result_JsonObject } from "../../../../../ActionDefinition/Action/Payload/ActionPayload.types";
+import type { ClientCryptoKeyLink } from "@nice-code/util";
+import type { TActionPayload_Any_JsonObject } from "../../../../../ActionDefinition/Action/Payload/ActionPayload.types";
+import type { IRuntimeCoordinate } from "../../../../RuntimeCoordinate";
 import type { ETransportType, IActionTransportDef, IActionTransportInitialized, IActionTransportReadyData_Base, ITransportRouteActionParams } from "../Transport.types";
+import type { ESecurityLevel } from "./actionWsHandshake";
+/**
+ * Client-side secure-channel config for a WebSocket. When present (and `securityLevel !== none`), the
+ * connection runs the {@link createClientHandshake} handshake during initialization — authenticating
+ * the identity and, for the `encrypted` level, deriving a shared key that encrypts every action frame.
+ */
+export interface IWsClientSecureChannel {
+    securityLevel: ESecurityLevel;
+    /** This client's crypto identity (verify + exchange key pairs, optionally persisted). */
+    link: ClientCryptoKeyLink;
+    /** This client's runtime coordinate — its authenticated identity to the server. */
+    localCoordinate: IRuntimeCoordinate;
+    /** Wire dictionary version; the server rejects the handshake on a mismatch. */
+    dictionaryVersion: string;
+}
 export interface IActionTransportReadyData_Ws extends IActionTransportReadyData_Base {
     formatMessage?: {
-        outgoing: (input: ITransportRouteActionParams) => string;
-        incoming?: (input: string) => IActionPayload_Result_JsonObject<any> | IActionPayload_Request_JsonObject<any> | undefined;
+        /**
+         * Pack an outgoing action payload. Return a `string` for text frames (JSON) or a binary
+         * `Uint8Array`/`ArrayBuffer` for optimized binary frames (e.g. msgpackr).
+         */
+        outgoing: (input: ITransportRouteActionParams) => string | Uint8Array | ArrayBuffer;
+        /**
+         * Unpack an incoming frame back into the wire JSON object the runtime hydrates + validates.
+         * Return `undefined` to defer to the connection's built-in JSON parser — this is how binary
+         * adapters stay backward compatible with plain-JSON clients on the same socket.
+         */
+        incoming?: (input: string | ArrayBuffer | Uint8Array | Blob) => TActionPayload_Any_JsonObject<any, any> | undefined;
     };
     ws: WebSocket;
+    /** Optional authenticated/encrypted channel; the connection runs the handshake during init. */
+    secureChannel?: IWsClientSecureChannel;
 }
 export interface IActionTransportInitialized_Ws extends IActionTransportInitialized<ITransportRouteActionParams, IActionTransportReadyData_Ws> {
 }

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketConnection.d.ts

@@ -10,7 +10,24 @@ export declare class WebSocketConnection extends TransportConnection<ETransportT
     protected _getCacheKey(_input: ITransportRouteActionParams): string;
     protected _processTransportStatus(input: ITransportRouteActionParams): TTransportStatusInfo<IActionTransportReadyData_Methods>;
     getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo | undefined;
+    private _isSecure;
+    private _awaitOpen;
+    /** Non-secure connections finalize synchronously; secure ones run the handshake first. */
+    private _finalize;
     _finalizeTransportMethods(wsData: IActionTransportReadyData_Ws): IActionTransportReadyData_Methods;
-    private _parseActionMessage;
+    /**
+     * Secure path: a single message listener feeds the handshake until it completes, then routes action
+     * frames (decrypting for the `encrypted` level). Frames that arrive in the gap between accept and
+     * activation are buffered and flushed, so nothing is lost.
+     */
+    private _finalizeSecureMethods;
+    private _runClientHandshake;
+    private _buildSendMethods;
+    /** Decode (and, when encrypted, decrypt) one inbound action frame and hand it to the runtime. */
+    private _handleIncomingActionFrame;
+    /** Accept text + binary frames (ArrayBuffer / Uint8Array / Blob); Blobs are converted to a buffer. */
+    private _normalizeFrame;
+    private _captureSocketUrl;
+    private _attachLifecycle;
     private _abortAll;
 }

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport.d.ts

@@ -3,8 +3,14 @@ import { ETransportType, type ITransportRouteActionParams, type ITransportRouteI
 import type { IActionTransportInitialized_Ws, IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
 import { WebSocketConnection } from "./WebSocketConnection";
 interface IWebSocketTransportSharedOptions {
-    /** Custom (de)serialization of action payloads on the wire. */
+    /** Custom (de)serialization of action payloads on the wire (shared across all sockets). */
     formatMessage?: IActionTransportReadyData_Ws["formatMessage"];
+    /**
+     * Per-socket codec factory — called once for each socket so stateful codecs (e.g. the
+     * `createBinaryWsSessionFactory` session, which holds per-connection correlation + identity state)
+     * get their own instance and reset cleanly on reconnect. Takes precedence over `formatMessage`.
+     */
+    createFormatMessage?: () => IActionTransportReadyData_Ws["formatMessage"];
     updateRunConfig?: TUpdateActionRunConfig;
     /**
      * Keys that identify a reusable socket, so a single socket is shared across actions to the same
@@ -13,6 +19,11 @@ interface IWebSocketTransportSharedOptions {
     getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
     /** Override the devtools route info for a specific action. */
     getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
+    /**
+     * Secure-channel config. When set (and `securityLevel !== none`), the connection runs the
+     * authenticated handshake during initialization and, at the `encrypted` level, encrypts every frame.
+     */
+    security?: IActionTransportReadyData_Ws["secureChannel"];
 }
 export interface IWebSocketTransportSocketOptions extends IWebSocketTransportSharedOptions {
     /** Open (or reuse) the WebSocket for an action — keep it simple or derive it per action. */

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/actionFrameCrypto.d.ts

@@ -0,0 +1,31 @@
+import type { ClientCryptoKeyLink, TTypeAndId } from "@nice-code/util";
+/**
+ * Async AES-GCM transform for the `encrypted` security level. It wraps the opaque binary frame a
+ * session codec produces (it does NOT look inside it), encrypting on the way out and decrypting on the
+ * way in with the shared key established by the handshake.
+ *
+ * It is deliberately separate from the (synchronous) session `formatMessage`: WebCrypto is always
+ * Promise-based, so encryption has to happen at the transport's async I/O boundary — the connection
+ * encrypts after `session.outgoing()` and decrypts before `session.incoming()`. The `authenticated`
+ * and `none` levels use no crypto transform at all (frames go out as the session produced them).
+ *
+ * Wire shape of an encrypted frame: `pack([nonceBytes, ciphertextBytes])` — msgpack carries the two
+ * binary fields with a couple of bytes of overhead, no base64 inflation.
+ */
+export interface IActionFrameCrypto {
+    /** Encrypt one session frame for sending. */
+    encryptFrame(frame: Uint8Array): Promise<Uint8Array>;
+    /** Decrypt one received frame back to the session frame. Throws on a non-binary / malformed /
+     * tampered frame — the caller (transport) decides how to react (drop / close). */
+    decryptFrame(frame: string | ArrayBuffer | Uint8Array): Promise<Uint8Array>;
+}
+export interface IActionFrameCryptoConfig {
+    link: ClientCryptoKeyLink;
+    /** The handshake-established link id for the remote (key + connection-registry id). */
+    linkedClientId: TTypeAndId;
+}
+/**
+ * Build the encrypt/decrypt transform for a connection whose handshake settled on the `encrypted`
+ * level. Keyed by the link + `linkedClientId`, so it reuses the cached shared AES-GCM key.
+ */
+export declare function createActionFrameCrypto({ link, linkedClientId, }: IActionFrameCryptoConfig): IActionFrameCrypto;

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/actionWireCodec.d.ts

@@ -0,0 +1,41 @@
+import type { IActionContext_Data_JsonObject } from "../../../../../ActionDefinition/Action/Context/ActionContext.types";
+import { EActionPayloadType, type TActionPayload_Any_JsonObject } from "../../../../../ActionDefinition/Action/Payload/ActionPayload.types";
+import type { ActionDomain } from "../../../../../ActionDefinition/Domain/ActionDomain";
+import type { TPossibleDomainIdList } from "../../../../../ActionDefinition/Domain/ActionDomain.types";
+/**
+ * Shared building blocks for the binary action codecs (the stateless {@link createBinaryWsAdapter} and
+ * the per-connection `createBinaryWsSessionFactory`). Both map a `domain:id` route to a tiny integer
+ * and reduce the verbose JSON wire to a positional tuple — they only differ in how much context they
+ * carry per frame, so the dictionary + payload (de)assembly live here.
+ */
+/**
+ * Tiny integer codes for the payload type, so the verbose `"request"`/`"result"`/`"progress"`
+ * strings never hit the wire. The index in {@link ReversePayloadType} must line up with the value.
+ */
+export declare const PayloadTypeToInt: Record<EActionPayloadType.request | EActionPayloadType.result | EActionPayloadType.progress, number>;
+export declare const ReversePayloadType: readonly [EActionPayloadType.request, EActionPayloadType.result, EActionPayloadType.progress];
+export interface IActionRouteMeta {
+    domain: string;
+    id: string;
+    allDomains: TPossibleDomainIdList;
+}
+export interface IActionRouteDictionary {
+    /** `domain:id` → wire integer. */
+    routeToInt: Map<string, number>;
+    /** wire integer → route metadata for reconstruction. */
+    intToRoute: IActionRouteMeta[];
+}
+/**
+ * Build the positional `domain:id` ↔ integer dictionary. Both ends of a channel MUST build it from
+ * the same domains in the same order — the mapping is positional, so a mismatch routes to the wrong
+ * action. Add new transported domains to the end of the list.
+ */
+export declare function buildActionRouteDictionary(domains: ActionDomain<any>[]): IActionRouteDictionary;
+/** Pull the type-specific payload (`input` / `result` / `progress`) out of a wire JSON object. */
+export declare function extractWirePayload(json: TActionPayload_Any_JsonObject<any, any>): unknown;
+/**
+ * Reassemble a full wire JSON object from its decoded parts. `inputHash`/`outputHash` are emitted
+ * empty — the hydration constructors recompute them — and the result still satisfies
+ * `isActionPayload_Any_JsonObject` so it flows through validation like a JSON frame.
+ */
+export declare function assembleWireJson(routeMeta: IActionRouteMeta, payloadType: (typeof ReversePayloadType)[number], time: number, context: IActionContext_Data_JsonObject, payloadData: any): TActionPayload_Any_JsonObject<any, any>;

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/actionWsHandshake.d.ts

@@ -0,0 +1,187 @@
+import { type ClientCryptoKeyLink, type StorageAdapter, type TSerializedCryptoKeyData_Ed25519_Raw, type TSerializedCryptoKeyData_X25519_Raw, type TTypeAndId } from "@nice-code/util";
+import * as v from "valibot";
+import { type IRuntimeCoordinate } from "../../../../RuntimeCoordinate";
+/** How much the channel protects after the handshake — chosen by the consumer (perf vs security). */
+export declare enum ESecurityLevel {
+    /** No handshake; identity is self-asserted (fastest, dev / trusted networks). */
+    none = "none",
+    /** Handshake authenticates identity (sign/verify + key pin); frames stay plaintext over TLS. */
+    authenticated = "authenticated",
+    /** Authenticated handshake + every frame AES-GCM encrypted with the derived shared key. */
+    encrypted = "encrypted"
+}
+export declare enum EHandshakeMessageType {
+    hello = "hello",
+    welcome = "welcome",
+    prove = "prove",
+    accept = "accept",
+    reject = "reject"
+}
+declare const vHsHello: v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.hello, undefined>;
+    readonly protocol: v.StringSchema<undefined>;
+    readonly securityLevel: v.PicklistSchema<[ESecurityLevel.none, ESecurityLevel.authenticated, ESecurityLevel.encrypted], undefined>;
+    readonly dictionaryVersion: v.StringSchema<undefined>;
+    readonly client: v.ObjectSchema<{
+        readonly envId: v.StringSchema<undefined>;
+        readonly perId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly insId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>;
+    readonly clientNonce: v.StringSchema<undefined>;
+    readonly verifyPublicKey: v.CustomSchema<`ed25519::raw_base64::${string}`, undefined>;
+    readonly exchangePublicKey: v.OptionalSchema<v.CustomSchema<`x25519::raw_base64::${string}`, undefined>, undefined>;
+}, undefined>;
+declare const vHsWelcome: v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.welcome, undefined>;
+    readonly securityLevel: v.PicklistSchema<[ESecurityLevel.none, ESecurityLevel.authenticated, ESecurityLevel.encrypted], undefined>;
+    readonly dictionaryVersion: v.StringSchema<undefined>;
+    readonly server: v.ObjectSchema<{
+        readonly envId: v.StringSchema<undefined>;
+        readonly perId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly insId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>;
+    readonly serverNonce: v.StringSchema<undefined>;
+    readonly verifyPublicKey: v.CustomSchema<`ed25519::raw_base64::${string}`, undefined>;
+    readonly exchangePublicKey: v.OptionalSchema<v.CustomSchema<`x25519::raw_base64::${string}`, undefined>, undefined>;
+}, undefined>;
+declare const vHsProve: v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.prove, undefined>;
+    readonly signatureBase64: v.StringSchema<undefined>;
+}, undefined>;
+declare const vHsAccept: v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.accept, undefined>;
+    readonly signatureBase64: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+declare const vHsReject: v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.reject, undefined>;
+    readonly reason: v.StringSchema<undefined>;
+}, undefined>;
+declare const vHandshakeMessage: v.VariantSchema<"t", [v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.hello, undefined>;
+    readonly protocol: v.StringSchema<undefined>;
+    readonly securityLevel: v.PicklistSchema<[ESecurityLevel.none, ESecurityLevel.authenticated, ESecurityLevel.encrypted], undefined>;
+    readonly dictionaryVersion: v.StringSchema<undefined>;
+    readonly client: v.ObjectSchema<{
+        readonly envId: v.StringSchema<undefined>;
+        readonly perId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly insId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>;
+    readonly clientNonce: v.StringSchema<undefined>;
+    readonly verifyPublicKey: v.CustomSchema<`ed25519::raw_base64::${string}`, undefined>;
+    readonly exchangePublicKey: v.OptionalSchema<v.CustomSchema<`x25519::raw_base64::${string}`, undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.welcome, undefined>;
+    readonly securityLevel: v.PicklistSchema<[ESecurityLevel.none, ESecurityLevel.authenticated, ESecurityLevel.encrypted], undefined>;
+    readonly dictionaryVersion: v.StringSchema<undefined>;
+    readonly server: v.ObjectSchema<{
+        readonly envId: v.StringSchema<undefined>;
+        readonly perId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly insId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>;
+    readonly serverNonce: v.StringSchema<undefined>;
+    readonly verifyPublicKey: v.CustomSchema<`ed25519::raw_base64::${string}`, undefined>;
+    readonly exchangePublicKey: v.OptionalSchema<v.CustomSchema<`x25519::raw_base64::${string}`, undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.prove, undefined>;
+    readonly signatureBase64: v.StringSchema<undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.accept, undefined>;
+    readonly signatureBase64: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly t: v.LiteralSchema<EHandshakeMessageType.reject, undefined>;
+    readonly reason: v.StringSchema<undefined>;
+}, undefined>], undefined>;
+export type THsHello = v.InferOutput<typeof vHsHello>;
+export type THsWelcome = v.InferOutput<typeof vHsWelcome>;
+export type THsProve = v.InferOutput<typeof vHsProve>;
+export type THsAccept = v.InferOutput<typeof vHsAccept>;
+export type THsReject = v.InferOutput<typeof vHsReject>;
+export type THandshakeMessage = v.InferOutput<typeof vHandshakeMessage>;
+/** Serialize a handshake message for the wire (handshake frames are JSON — they aren't the hot path). */
+export declare function encodeHandshakeMessage(message: THandshakeMessage): string;
+/** Parse + structurally validate an incoming handshake frame; `undefined` if it isn't one. */
+export declare function decodeHandshakeMessage(raw: string): THandshakeMessage | undefined;
+/** Stable link id for a runtime coordinate — the key both the crypto link and the connection use. */
+export declare function runtimeLinkId(coordinate: IRuntimeCoordinate): TTypeAndId;
+/**
+ * Everything needed to re-derive the shared AES-GCM key for an `encrypted` link after a restart —
+ * the remote's public keys + the HKDF salt/info used at handshake time. The local (server) key pair is
+ * recovered from its own persisted `ClientCryptoKeyLink` storage, so re-linking with this material
+ * yields the identical shared key without a fresh handshake.
+ */
+export interface IHandshakeEncryptionKeyMaterial {
+    verifyPublicKey: TSerializedCryptoKeyData_Ed25519_Raw;
+    exchangePublicKey: TSerializedCryptoKeyData_X25519_Raw;
+    saltString: string;
+    infoString: string;
+    bindVerifyKeysIntoDerivation: boolean;
+}
+/** Outcome of a completed handshake — what the transport/handler needs to wire the channel. */
+export interface IHandshakeResult {
+    /** The crypto-link id (and connection-registry key) for the authenticated remote. */
+    linkedClientId: TTypeAndId;
+    /** The remote's authenticated coordinate. */
+    remote: IRuntimeCoordinate;
+    securityLevel: ESecurityLevel;
+    /** For the `encrypted` level: material to restore the shared key after eviction (persist it). */
+    encryptionKeyMaterial?: IHandshakeEncryptionKeyMaterial;
+}
+export interface IClientVerifyKeyResolveInput {
+    client: IRuntimeCoordinate;
+    verifyPublicKey: TSerializedCryptoKeyData_Ed25519_Raw;
+}
+export interface IClientVerifyKeyResolver {
+    /**
+     * Decide whether a presented verify key is trusted for a client identity. The signature is already
+     * verified by the time this runs, so this is purely the identity-pinning decision. Swap in a
+     * persistent / pre-provisioned implementation without touching the protocol.
+     */
+    resolve(input: IClientVerifyKeyResolveInput): Promise<{
+        trusted: boolean;
+        reason?: string;
+    }>;
+}
+/**
+ * In-memory trust-on-first-use resolver: trusts (and pins) the first verify key seen for a client
+ * identity, then rejects a different key for that identity. The default; replace with a storage-backed
+ * resolver for cross-restart pinning (see Step 5).
+ */
+export declare function createInMemoryTofuVerifyKeyResolver(): IClientVerifyKeyResolver;
+/**
+ * Storage-backed trust-on-first-use resolver: pins survive process restarts / Durable Object eviction
+ * (e.g. back it with `createDurableObjectStorageAdapter`). Same policy as the in-memory variant — trust
+ * + pin the first verify key per client identity, reject a different one thereafter.
+ */
+export declare function createStorageTofuVerifyKeyResolver(storageAdapter: StorageAdapter): IClientVerifyKeyResolver;
+export interface IClientHandshakeConfig {
+    link: ClientCryptoKeyLink;
+    localCoordinate: IRuntimeCoordinate;
+    dictionaryVersion: string;
+    securityLevel: ESecurityLevel;
+}
+export declare function createClientHandshake(config: IClientHandshakeConfig): {
+    createHello(): Promise<THsHello>;
+    onWelcome(welcome: THsWelcome): Promise<THsProve>;
+    onAccept(accept: THsAccept): Promise<IHandshakeResult>;
+};
+export interface IServerHandshakeConfig {
+    link: ClientCryptoKeyLink;
+    localCoordinate: IRuntimeCoordinate;
+    dictionaryVersion: string;
+    /**
+     * The level(s) this server accepts. A single level is strict (the client must match). An array is a
+     * negotiable allowed set — the server adopts whichever level the client requests, as long as it's in
+     * the set (lets one backend serve `authenticated` and `encrypted` clients at once). `none` in the set
+     * is handled by the transport/handler (a `none` client never reaches the handshake).
+     */
+    securityLevel: ESecurityLevel | readonly ESecurityLevel[];
+    /** Trust decision for a client's verify key. Defaults to in-memory TOFU. */
+    verifyKeyResolver?: IClientVerifyKeyResolver;
+}
+export declare function createServerHandshake(config: IServerHandshakeConfig): {
+    onHello(hello: THsHello): Promise<THsWelcome | THsReject>;
+    onProve(prove: THsProve): Promise<THsAccept | THsReject>;
+    /** The completed handshake result once `onProve` has accepted, else `undefined`. */
+    getResult(): IHandshakeResult | undefined;
+};
+export {};

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/createBinaryWsAdapter.d.ts

@@ -0,0 +1,20 @@
+import type { ActionDomain } from "../../../../../ActionDefinition/Domain/ActionDomain";
+import type { IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
+/**
+ * Builds a *stateless* `formatMessage` pipeline for {@link WebSocketTransport}, packing action
+ * payloads into a compact msgpackr binary frame instead of JSON. The `domain`/`id` route collapses to
+ * a single integer drawn from a shared dictionary; `form`/`type`, the recomputable
+ * `inputHash`/`outputHash`, and the per-frame `context.routing`/`context.timeCreated` are all dropped
+ * (see {@link ENVELOPE}).
+ *
+ * No validation runs here: `incoming` blindly reconstructs the wire JSON shape and hands it back to
+ * the connection, which flows into `ActionRuntime` → `domain.hydrateAnyAction()` where the Valibot
+ * schemas validate it exactly as they would for a JSON frame.
+ *
+ * Both ends of the socket MUST construct the adapter with the same domains in the same order — the
+ * integer dictionary is positional. Mismatched dictionaries will route to the wrong action.
+ *
+ * Because `incoming` returns `undefined` for text frames, a binary server can still serve plain-JSON
+ * clients on the same runtime (the connection falls back to its built-in JSON parser).
+ */
+export declare function createBinaryWsAdapter(domains: ActionDomain<any>[]): NonNullable<IActionTransportReadyData_Ws["formatMessage"]>;

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/createBinaryWsSessionFactory.d.ts

@@ -0,0 +1,31 @@
+import type { ActionDomain } from "../../../../../ActionDefinition/Domain/ActionDomain";
+import type { IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
+type TFormatMessage = NonNullable<IActionTransportReadyData_Ws["formatMessage"]>;
+export interface IBinaryWsSessionOptions {
+    /** Override how long an unresolved correlation is retained before being swept (ms). */
+    correlationTtlMs?: number;
+}
+/**
+ * Builds a factory of *stateful, per-connection* codecs for {@link WebSocketTransport} /
+ * `ActionServerHandler` — the maximally compact binary wire. Call the returned factory once per live
+ * connection (each socket on the client, each accepted connection on the server) so every channel
+ * gets its own correlation + identity state.
+ *
+ * On top of everything {@link createBinaryWsAdapter} drops, a session also drops:
+ * - **`cuid`** — replaced by a per-connection integer correlation id. The initiator maps it to its
+ *   real cuid; the responder echoes it; each side reconstructs the cuid from its own map. Correlation
+ *   only needs to be unique per socket, so a counter suffices.
+ * - **`originClient` after the first request** — the first request each side sends carries its
+ *   identity; the peer remembers it and injects it into later frames. Replies omit it entirely (a
+ *   reply carries the initiator's own origin, which the initiator already knows).
+ *
+ * Both ends MUST build the factory from the same domains in the same order (positional dictionary).
+ * Text frames still return `undefined` from `incoming`, so JSON clients remain interoperable.
+ *
+ * Hibernation note: after a server connection is evicted its session resets, so a still-connected
+ * client (whose session persists) will keep omitting `originClient`. The server must therefore restore
+ * the connection→client binding from its own store (see `ActionServerHandler.rehydrateConnection`) and
+ * inject `originClient` from there — the session alone can't recover it.
+ */
+export declare function createBinaryWsSessionFactory(domains: ActionDomain<any>[], options?: IBinaryWsSessionOptions): () => TFormatMessage;
+export {};

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/ws_util.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Send a text or binary frame over a socket. A binary formatter may hand back a `Uint8Array` whose
+ * backing buffer is typed as `ArrayBufferLike` (msgpackr pools buffers / may be `SharedArrayBuffer`),
+ * which `WebSocket.send`'s `BufferSource` parameter rejects — copy it into a fresh `ArrayBuffer`-backed
+ * view so the type (and the bytes) are safe to send.
+ */
+export declare function sendFrame(ws: WebSocket, data: string | Uint8Array | ArrayBuffer): void;
+/** Normalize any frame form to bytes (for the AES-GCM layer, which works on `Uint8Array`). */
+export declare function toFrameBytes(frame: string | Uint8Array | ArrayBuffer): Uint8Array;
 /** Compact a WebSocket URL to `host/pathname` for devtools display, falling back to the raw url. */
 export declare function shortWs(url: string): string;

package/build/types/ActionRuntime/Handler/Server/ActionServerHandler.d.ts

@@ -0,0 +1,191 @@
+import type { ClientCryptoKeyLink, TTypeAndId } from "@nice-code/util";
+import type { IActionRouteItemHandler } from "../../../ActionDefinition/Action/Payload/ActionPayload.types";
+import { type TActionPayload_Any_Instance, type TActionPayload_Any_JsonObject } from "../../../ActionDefinition/Action/Payload/ActionPayload.types";
+import type { ActionPayload_Request } from "../../../ActionDefinition/Action/Payload/ActionPayload_Request";
+import { RunningAction } from "../../../ActionDefinition/Action/RunningAction";
+import type { IActionDomain } from "../../../ActionDefinition/Domain/ActionDomain.types";
+import { ActionRuntime } from "../../ActionRuntime";
+import { type IRuntimeCoordinate, RuntimeCoordinate } from "../../RuntimeCoordinate";
+import type { IHandleActionOptions } from "../ActionHandler.types";
+import { ActionExternalClientHandler } from "../ExternalClient/ActionExternalClientHandler";
+import { ESecurityLevel, type IClientVerifyKeyResolver, type IHandshakeEncryptionKeyMaterial } from "../ExternalClient/Transport/WebSocket/actionWsHandshake";
+import type { IActionTransportReadyData_Ws } from "../ExternalClient/Transport/WebSocket/TransportWebSocket.types";
+/** The codec shape `ActionServerHandler` uses to pack/unpack frames — same as the WS transport's. */
+export type TActionChannelFormatMessage = NonNullable<IActionTransportReadyData_Ws["formatMessage"]>;
+/** How a connection encodes its frames, remembered so we answer each client in its own dialect. */
+export type TActionConnectionEncoding = "json" | "binary";
+/** A connection's restorable identity — what to persist so a binding survives transport eviction. */
+export interface IActionServerConnectionBinding {
+    /** Full client coordinate, so `originClient` can be re-injected into frames that omit it. */
+    client: IRuntimeCoordinate;
+    encoding: TActionConnectionEncoding;
+    /**
+     * Secure-session state (set once a connection's handshake completes). Persist it alongside the
+     * binding so an authenticated/encrypted connection resumes after eviction without re-handshaking —
+     * the `keyMaterial` lets the server re-derive the shared key from its own persisted identity.
+     */
+    secure?: {
+        securityLevel: ESecurityLevel;
+        linkedClientId: TTypeAndId;
+        keyMaterial?: IHandshakeEncryptionKeyMaterial;
+    };
+}
+/**
+ * Server-side secure-channel config. When set, each connection negotiates a level from
+ * {@link securityLevel}: an `authenticated`/`encrypted` client must complete the handshake (and is then
+ * bound to its *authenticated* coordinate) before any action frame is accepted. A `none` client (only
+ * when `none` is in the allowed set) is accepted as-is with a self-asserted identity. For the
+ * `encrypted` level the codec source should be a session factory (`createFormatMessage`).
+ */
+export interface IActionServerSecurity {
+    /**
+     * Accepted level(s). A single level is strict; an array is a negotiable allowed set — the server
+     * adopts whichever level each client requests (e.g. `[none, authenticated, encrypted]` serves all
+     * three over one endpoint).
+     */
+    securityLevel: ESecurityLevel | readonly ESecurityLevel[];
+    /** This server's crypto identity (verify + exchange key pairs, optionally persisted). */
+    link: ClientCryptoKeyLink;
+    /** This server's coordinate — its identity to clients during the handshake. */
+    localCoordinate: IRuntimeCoordinate;
+    /** Wire dictionary version; the handshake rejects a client on a mismatch. */
+    dictionaryVersion: string;
+    /** Trust decision for a client's verify key (defaults to in-memory TOFU inside the handshake). */
+    verifyKeyResolver?: IClientVerifyKeyResolver;
+}
+interface IActionServerHandlerBaseOptions<TConn> {
+    /**
+     * Coordinate of the *connecting clients* (typically env-only, e.g. `RuntimeCoordinate.env("web_app")`).
+     * The runtime's return-path dispatch scores incoming actions' `originClient` against this to pick
+     * this handler for sending results/pushes back over the right channel.
+     */
+    clientEnv: RuntimeCoordinate;
+    /** Write an encoded frame to a specific live connection (e.g. `(ws, frame) => ws.send(frame)`). */
+    send: (connection: TConn, frame: string | Uint8Array | ArrayBuffer) => void;
+    /** Timeout (ms) applied to server-initiated actions awaiting a client response. */
+    defaultTimeout?: number;
+    /**
+     * Called once when a connection is first bound to a client identity. Use it to persist the binding
+     * for transports that can resume after eviction — e.g. a Durable Object's hibernatable WebSocket:
+     * `(ws, binding) => ws.serializeAttachment(binding)` — then replay it via {@link ActionServerHandler.rehydrateConnection}
+     * when the channel comes back.
+     */
+    onConnectionBound?: (connection: TConn, binding: IActionServerConnectionBinding) => void;
+    /**
+     * Enable the authenticated (optionally encrypted) handshake. When omitted, connections are trusted
+     * as-is (identity self-asserted) — fine for dev / trusted networks.
+     */
+    security?: IActionServerSecurity;
+}
+/**
+ * Provide exactly one codec source:
+ * - `formatMessage` — a single shared codec for every connection (stateless, e.g. `createBinaryWsAdapter`).
+ * - `createFormatMessage` — a per-connection factory for stateful codecs (e.g.
+ *   `createBinaryWsSessionFactory`, whose sessions hold correlation + identity state). Required for the
+ *   leanest binary wire; the handler creates and caches one codec per connection.
+ */
+export type IActionServerHandlerOptions<TConn> = IActionServerHandlerBaseOptions<TConn> & ({
+    formatMessage: TActionChannelFormatMessage;
+    createFormatMessage?: never;
+} | {
+    createFormatMessage: () => TActionChannelFormatMessage;
+    formatMessage?: never;
+});
+/**
+ * Server-side handler for backends that accept many client connections over a single open channel
+ * (WebSockets, Durable Objects, …). It is transport-agnostic: you feed it inbound frames with
+ * {@link receive} and tell it how to write outbound frames via the `send` option.
+ *
+ * Add it alongside your local execution handler:
+ * ```ts
+ * const serverHandler = createServerHandler({ clientEnv, formatMessage, send: (ws, f) => ws.send(f) });
+ * runtime.addHandlers([localHandler, serverHandler]);
+ * // per inbound message (e.g. a Durable Object's webSocketMessage):
+ * serverHandler.receive(ws, message);
+ * ```
+ *
+ * Inbound requests route to your local handler; the runtime's return dispatch then calls this
+ * handler back (it is an external handler keyed to `clientEnv`) to send the result to the originating
+ * connection. The handler keeps a per-connection identity registry so each result lands on the right
+ * socket, and remembers each connection's encoding so binary and JSON clients can share the channel.
+ *
+ * It registers an empty action router, so it is never chosen to *execute* an inbound request — only
+ * to ferry results/pushes back out.
+ */
+export declare class ActionServerHandler<TConn = unknown> extends ActionExternalClientHandler {
+    private readonly _formatMessage?;
+    private readonly _createFormatMessage?;
+    private readonly _send;
+    private readonly _serverTimeout;
+    private readonly _onConnectionBound?;
+    /** Incoming-data listeners installed by the runtime (`resolveIncomingActionPayload`). */
+    private readonly _incomingListeners;
+    private readonly _security?;
+    /** Normalized accepted levels; whether `none` (plain) is allowed; whether any level needs a handshake. */
+    private readonly _allowedLevels;
+    private readonly _noneAllowed;
+    private readonly _handshakeMode;
+    private readonly _connByClient;
+    private readonly _clientByConn;
+    private readonly _connEncoding;
+    private readonly _codecByConn;
+    private readonly _handshakeByConn;
+    private readonly _cryptoByConn;
+    private readonly _authedConns;
+    private readonly _plainConns;
+    private readonly _inboundChainByConn;
+    private readonly _outboundChainByConn;
+    constructor(options: IActionServerHandlerOptions<TConn>);
+    /**
+     * The codec for a connection: a per-connection session (cached) when a factory was provided, else
+     * the single shared `formatMessage`.
+     */
+    private _codecFor;
+    _setIncomingActionDataListener(listener: (json: TActionPayload_Any_JsonObject<any>) => void): void;
+    /**
+     * Feed one inbound frame from a connection into the runtime. Decodes text or binary, binds the
+     * connection to the requesting client's identity, then routes it (requests execute locally;
+     * results/progress resolve pending server-initiated actions).
+     */
+    receive(connection: TConn, frame: string | ArrayBuffer | Uint8Array): void;
+    private _receivePlain;
+    private _receiveSecure;
+    private _completeServerHandshake;
+    /**
+     * Ensure an inbound request carries the client's identity and that this connection is bound to it,
+     * so its result can be routed back. A session codec omits `originClient` after the first request, so
+     * when it's missing we restore it from the (possibly rehydrated) binding instead. (Plain mode only;
+     * secure mode binds the authenticated coordinate at handshake time.)
+     */
+    private _resolveRequestIdentity;
+    /**
+     * Restore a connection→client binding without an inbound frame — for transports that resume after
+     * eviction. Pair it with the {@link IActionServerHandlerOptions.onConnectionBound} hook: persist
+     * the binding there, then replay each live connection here when the channel comes back (e.g. a
+     * Durable Object iterating `ctx.getWebSockets()` as it wakes from hibernation).
+     */
+    rehydrateConnection(connection: TConn, binding: IActionServerConnectionBinding): void;
+    toHandlerRouteItem(): IActionRouteItemHandler;
+    /** Forget a connection (call on socket close) so stale entries don't misroute later results. */
+    dropConnection(connection: TConn): void;
+    /** Live connection for a client coordinate, if currently registered. */
+    getConnectionForClient(client: RuntimeCoordinate): TConn | undefined;
+    /**
+     * Send (and optionally await) a server-initiated action to a specific connected client. Pass the
+     * connection token directly (e.g. the `ws`) or a client `RuntimeCoordinate` to look one up.
+     */
+    pushToClient<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(runtime: ActionRuntime, target: TConn | RuntimeCoordinate, request: ActionPayload_Request<DOM, ID>, options?: {
+        timeout?: number;
+    }): RunningAction<DOM, ID>;
+    sendReturnPayload(payload: TActionPayload_Any_Instance<any, any>, config: {
+        targetLocalRuntime: ActionRuntime;
+    }): Promise<boolean>;
+    handleActionRequest<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions): Promise<RunningAction<DOM, ID>>;
+    private _dispatch;
+    private _sendPayload;
+    private _bindConnection;
+    private _resolveConnection;
+    private _resolveSingleConnection;
+}
+export declare const createServerHandler: <TConn = unknown>(options: IActionServerHandlerOptions<TConn>) => ActionServerHandler<TConn>;
+export {};

package/build/types/devtools/browser/components/SectionLabel.d.ts

@@ -1,4 +1,4 @@
-export declare function SectionLabel({ label, color }: {
+export declare function SectionLabel({ label, color, }: {
     label: string;
     color?: string;
 }): import("react/jsx-runtime").JSX.Element;