@nice-code/action 0.6.3 → 0.7.0

package/build/index.js

@@ -2956,6 +2956,9 @@ function createBinaryWsSessionFactory(domains, options) {
     };
   };
 }
+// src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/secureWsChannel.ts
+import { ClientCryptoKeyLink } from "@nice-code/util";
+
 // src/utils/decodeActionFrame.ts
 function decodeActionFrame(frame, decoder) {
   const decoded = decoder?.incoming?.(frame) ?? (typeof frame === "string" ? parseJsonActionFrame(frame) : undefined);
@@ -3313,6 +3316,44 @@ class WebSocketTransport extends Transport {
     };
   }
 }
+
+// src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/secureWsChannel.ts
+function deriveDictionaryVersion(domains) {
+  const { intToRoute } = buildActionRouteDictionary(domains);
+  const signature = intToRoute.map((route) => `${route.domain}:${route.id}`).join(",");
+  let hash = 2166136261;
+  for (let i = 0;i < signature.length; i++) {
+    hash ^= signature.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `auto:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function defineSecureWsChannel(options) {
+  return {
+    dictionaryVersion: options.dictionaryVersion ?? deriveDictionaryVersion(options.domains),
+    createCodec: createBinaryWsSessionFactory(options.domains, options.sessionOptions)
+  };
+}
+function createSecureWebSocketTransport(options) {
+  const link = new ClientCryptoKeyLink({ storageAdapter: options.storageAdapter });
+  return WebSocketTransport.create({
+    createWebSocket: options.createWebSocket ?? (() => {
+      const ws = new WebSocket(options.url);
+      ws.binaryType = "arraybuffer";
+      return ws;
+    }),
+    getTransportCacheKey: options.getTransportCacheKey ?? (() => [options.url]),
+    createFormatMessage: options.channel.createCodec,
+    updateRunConfig: options.updateRunConfig,
+    getRouteInfo: options.getRouteInfo,
+    security: {
+      securityLevel: options.securityLevel,
+      link,
+      localCoordinate: options.runtime.coordinate.toJsonObject(),
+      dictionaryVersion: options.channel.dictionaryVersion
+    }
+  });
+}
 // src/ActionRuntime/Handler/Server/ActionServerHandler.ts
 class ActionServerHandler extends ActionExternalClientHandler {
   _formatMessage;
@@ -3365,6 +3406,9 @@ class ActionServerHandler extends ActionExternalClientHandler {
   _setIncomingActionDataListener(listener) {
     this._incomingListeners.push(listener);
   }
+  setOnConnectionBound(onConnectionBound) {
+    this._onConnectionBound = onConnectionBound;
+  }
   receive(connection, frame) {
     if (this._security == null || !this._handshakeMode) {
       this._receivePlain(connection, frame);
@@ -3627,6 +3671,42 @@ class ActionServerHandler extends ActionExternalClientHandler {
 var createServerHandler = (options) => {
   return new ActionServerHandler(options);
 };
+// src/ActionRuntime/Handler/Server/createSecureActionServer.ts
+import { ClientCryptoKeyLink as ClientCryptoKeyLink2 } from "@nice-code/util";
+var DEFAULT_SERVER_SECURITY_LEVELS = [
+  "none" /* none */,
+  "authenticated" /* authenticated */,
+  "encrypted" /* encrypted */
+];
+function createSecureActionServerHandler(options) {
+  const link = new ClientCryptoKeyLink2({ storageAdapter: options.storageAdapter });
+  return new ActionServerHandler({
+    clientEnv: options.clientEnv,
+    createFormatMessage: options.channel.createCodec,
+    send: options.send,
+    defaultTimeout: options.defaultTimeout,
+    security: {
+      securityLevel: options.securityLevel ?? DEFAULT_SERVER_SECURITY_LEVELS,
+      link,
+      localCoordinate: options.runtime.coordinate.toJsonObject(),
+      dictionaryVersion: options.channel.dictionaryVersion,
+      verifyKeyResolver: options.verifyKeyResolver ?? createStorageTofuVerifyKeyResolver(options.storageAdapter)
+    }
+  });
+}
+function createHibernatableWsServerAdapter(options) {
+  const { handler, getWebSockets, getAttachment, setAttachment } = options;
+  handler.setOnConnectionBound(setAttachment);
+  for (const connection of getWebSockets()) {
+    const binding = getAttachment(connection);
+    if (binding != null)
+      handler.rehydrateConnection(connection, binding);
+  }
+  return {
+    receive: (connection, frame) => handler.receive(connection, frame),
+    drop: (connection) => handler.dropConnection(connection)
+  };
+}
 export {
   runtimeLinkId,
   isActionPayload_Result_JsonObject,
@@ -3637,13 +3717,17 @@ export {
   err_nice_external_client,
   err_nice_action,
   encodeHandshakeMessage,
+  defineSecureWsChannel,
   decodeHandshakeMessage,
   decodeActionFrame,
   createStorageTofuVerifyKeyResolver,
   createServerHandshake,
   createServerHandler,
+  createSecureWebSocketTransport,
+  createSecureActionServerHandler,
   createLocalHandler,
   createInMemoryTofuVerifyKeyResolver,
+  createHibernatableWsServerAdapter,
   createExternalClientHandler,
   createClientHandshake,
   createBinaryWsSessionFactory,

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

@@ -0,0 +1,63 @@
+import { type StorageAdapter } from "@nice-code/util";
+import type { ActionDomain } from "../../../../../ActionDefinition/Domain/ActionDomain";
+import type { ActionRuntime } from "../../../../ActionRuntime";
+import type { ITransportRouteActionParams, ITransportRouteInfo, TUpdateActionRunConfig } from "../Transport.types";
+import { ESecurityLevel } from "./actionWsHandshake";
+import { type IBinaryWsSessionOptions } from "./createBinaryWsSessionFactory";
+import type { IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
+import { WebSocketTransport } from "./WebSocketTransport";
+/** The per-connection binary session codec — built once per socket from the channel's domains. */
+type TChannelCodec = NonNullable<IActionTransportReadyData_Ws["formatMessage"]>;
+/**
+ * The shared identity of a secure WebSocket channel: the wire dictionary version both ends check
+ * during the handshake, plus the per-connection codec factory both ends build from the *same* domain
+ * list. Define it once (typically in code shared by client and server) and hand it to
+ * {@link createSecureWebSocketTransport} on the client and `createSecureActionServerHandler` on the
+ * server, so the codec and version can never drift apart.
+ */
+export interface ISecureWsChannel {
+    /** Wire dictionary version — derived from the domains by default; the handshake rejects a mismatch. */
+    dictionaryVersion: string;
+    /** Per-connection session codec factory (call once per live connection). */
+    createCodec: () => TChannelCodec;
+}
+/**
+ * Bundle a secure channel's shared identity from its transported domains. Both ends MUST call this
+ * with the same domains in the same order (the binary wire dictionary is positional). The
+ * `dictionaryVersion` is derived from those domains unless you pin an explicit one.
+ */
+export declare function defineSecureWsChannel(options: {
+    /** Domains transported over this channel, in a stable order. Add new ones to the *end*. */
+    domains: ActionDomain<any>[];
+    /** Pin a human-readable version instead of the derived hash (must match on both ends). */
+    dictionaryVersion?: string;
+    /** Tuning for the per-connection binary session (e.g. correlation TTL). */
+    sessionOptions?: IBinaryWsSessionOptions;
+}): ISecureWsChannel;
+export interface ISecureWebSocketTransportOptions {
+    /** The shared channel identity (codec + dictionary version). */
+    channel: ISecureWsChannel;
+    /** This client's runtime — its coordinate is the authenticated identity sent in the handshake. */
+    runtime: ActionRuntime;
+    /** Backing store for this client's crypto identity (a stable verify key across reloads). */
+    storageAdapter: StorageAdapter;
+    /** The level this client requests; the server must allow it. */
+    securityLevel: ESecurityLevel;
+    /** Endpoint URL — drives both the socket and the per-endpoint cache key. */
+    url: string;
+    /** Override socket creation (defaults to a `new WebSocket(url)` with `binaryType = "arraybuffer"`). */
+    createWebSocket?: (input: ITransportRouteActionParams) => WebSocket;
+    /** Override the reuse key (defaults to `[url]`, so one socket is shared per endpoint). */
+    getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
+    updateRunConfig?: TUpdateActionRunConfig;
+    getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
+}
+/**
+ * Build a {@link WebSocketTransport} for the secure binary channel with the boilerplate folded in: it
+ * creates the {@link ClientCryptoKeyLink} from `storageAdapter`, opens an `arraybuffer` socket to
+ * `url`, caches it per endpoint, installs the channel's per-connection codec, and assembles the
+ * `security` block from the runtime coordinate + channel version. Pass `createWebSocket` /
+ * `getTransportCacheKey` to take over those bits when you need to.
+ */
+export declare function createSecureWebSocketTransport(options: ISecureWebSocketTransportOptions): WebSocketTransport;
+export {};

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

@@ -117,7 +117,7 @@ export declare class ActionServerHandler<TConn = unknown> extends ActionExternal
     private readonly _createFormatMessage?;
     private readonly _send;
     private readonly _serverTimeout;
-    private readonly _onConnectionBound?;
+    private _onConnectionBound?;
     /** Incoming-data listeners installed by the runtime (`resolveIncomingActionPayload`). */
     private readonly _incomingListeners;
     private readonly _security?;
@@ -142,6 +142,12 @@ export declare class ActionServerHandler<TConn = unknown> extends ActionExternal
      */
     private _codecFor;
     _setIncomingActionDataListener(listener: (json: TActionPayload_Any_JsonObject<any>) => void): void;
+    /**
+     * Register (or replace) the connection-bound persistence callback after construction. Used by
+     * lifecycle helpers like {@link createHibernatableWsServerAdapter} so persistence and replay are
+     * owned by one place instead of being split across the constructor options.
+     */
+    setOnConnectionBound(onConnectionBound: (connection: TConn, binding: IActionServerConnectionBinding) => 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;

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

@@ -0,0 +1,71 @@
+import { type StorageAdapter } from "@nice-code/util";
+import type { ActionRuntime } from "../../ActionRuntime";
+import type { RuntimeCoordinate } from "../../RuntimeCoordinate";
+import { ESecurityLevel, type IClientVerifyKeyResolver } from "../ExternalClient/Transport/WebSocket/actionWsHandshake";
+import type { ISecureWsChannel } from "../ExternalClient/Transport/WebSocket/secureWsChannel";
+import { ActionServerHandler, type IActionServerConnectionBinding } from "./ActionServerHandler";
+export interface ISecureActionServerHandlerOptions<TConn> {
+    /** The shared channel identity (codec + dictionary version) — same one the clients use. */
+    channel: ISecureWsChannel;
+    /**
+     * Coordinate of the *connecting clients* (typically env-only, e.g. `RuntimeCoordinate.env("web_app")`),
+     * used to route results/pushes back over this handler.
+     */
+    clientEnv: RuntimeCoordinate;
+    /** This server's runtime — its coordinate is the server identity presented in the handshake. */
+    runtime: ActionRuntime;
+    /**
+     * One backing store for the server's crypto identity *and* its trust-on-first-use verify-key pins.
+     * Their keys don't collide, so a single adapter is enough; back it with persistent storage (e.g. a
+     * Durable Object's storage) so identity and pins survive eviction.
+     */
+    storageAdapter: StorageAdapter;
+    /** Write an encoded frame to a specific live connection (e.g. `(ws, frame) => ws.send(frame)`). */
+    send: (connection: TConn, frame: string | Uint8Array | ArrayBuffer) => void;
+    /** Accepted level(s); defaults to negotiating any of none/authenticated/encrypted. */
+    securityLevel?: ESecurityLevel | readonly ESecurityLevel[];
+    /** Trust decision for a client's verify key; defaults to storage-backed TOFU over `storageAdapter`. */
+    verifyKeyResolver?: IClientVerifyKeyResolver;
+    /** Timeout (ms) applied to server-initiated actions awaiting a client response. */
+    defaultTimeout?: number;
+}
+/**
+ * Build an {@link ActionServerHandler} for the secure binary channel with the boilerplate folded in:
+ * it creates the {@link ClientCryptoKeyLink} and the storage-backed TOFU resolver from a single
+ * `storageAdapter`, installs the channel's per-connection codec, and assembles the `security` block
+ * from the runtime coordinate + channel version (accepting all three levels by default).
+ *
+ * For a hibernatable transport (e.g. a Durable Object), pair it with
+ * {@link createHibernatableWsServerAdapter} to wire persistence + replay.
+ */
+export declare function createSecureActionServerHandler<TConn = unknown>(options: ISecureActionServerHandlerOptions<TConn>): ActionServerHandler<TConn>;
+export interface IHibernatableWsServerAdapterOptions<TConn> {
+    /** The handler to drive (from {@link createSecureActionServerHandler} or `createServerHandler`). */
+    handler: ActionServerHandler<TConn>;
+    /** All currently-live connections — replayed on construction to rebuild bindings after a wake. */
+    getWebSockets: () => TConn[];
+    /** Read a connection's persisted binding (e.g. `(ws) => ws.deserializeAttachment()`). */
+    getAttachment: (connection: TConn) => IActionServerConnectionBinding | undefined;
+    /** Persist a connection's binding when it is bound (e.g. `(ws, b) => ws.serializeAttachment(b)`). */
+    setAttachment: (connection: TConn, binding: IActionServerConnectionBinding) => void;
+}
+export interface IHibernatableWsServerAdapter<TConn> {
+    /** Feed one inbound frame from a connection into the handler. */
+    receive: (connection: TConn, frame: string | ArrayBuffer | Uint8Array) => void;
+    /** Forget a connection (call on socket close/error). */
+    drop: (connection: TConn) => void;
+}
+/**
+ * Wire the hibernation lifecycle for a server handler on a transport whose sockets outlive process
+ * eviction (e.g. a Durable Object's hibernatable WebSockets). It owns persistence end to end:
+ * registers `setAttachment` as the handler's connection-bound callback and immediately replays every
+ * live connection's stored binding via `getAttachment`, so results/pushes still route after a wake.
+ *
+ * Construct it once when the handler is built, then forward socket events:
+ * ```ts
+ * const wsServer = createHibernatableWsServerAdapter({ handler, getWebSockets, getAttachment, setAttachment });
+ * // webSocketMessage(ws, msg) => wsServer.receive(ws, msg);
+ * // webSocketClose/Error(ws)  => wsServer.drop(ws);
+ * ```
+ */
+export declare function createHibernatableWsServerAdapter<TConn>(options: IHibernatableWsServerAdapterOptions<TConn>): IHibernatableWsServerAdapter<TConn>;

package/build/types/index.d.ts

@@ -26,10 +26,12 @@ export { createActionFrameCrypto, type IActionFrameCrypto, type IActionFrameCryp
 export { createClientHandshake, createInMemoryTofuVerifyKeyResolver, createServerHandshake, createStorageTofuVerifyKeyResolver, decodeHandshakeMessage, EHandshakeMessageType, ESecurityLevel, encodeHandshakeMessage, type IClientHandshakeConfig, type IClientVerifyKeyResolveInput, type IClientVerifyKeyResolver, type IHandshakeEncryptionKeyMaterial, type IHandshakeResult, type IServerHandshakeConfig, runtimeLinkId, type THandshakeMessage, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/actionWsHandshake";
 export { createBinaryWsAdapter } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/createBinaryWsAdapter";
 export { createBinaryWsSessionFactory, type IBinaryWsSessionOptions, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/createBinaryWsSessionFactory";
+export { createSecureWebSocketTransport, defineSecureWsChannel, type ISecureWebSocketTransportOptions, type ISecureWsChannel, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/secureWsChannel";
 export type { IActionTransportDef_Ws, IActionTransportInitialized_Ws, IActionTransportReadyData_Ws, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/TransportWebSocket.types";
 export { type IWebSocketTransportAdvancedOptions, type IWebSocketTransportSocketOptions, type TWebSocketTransportOptions, WebSocketTransport, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport";
 export { ActionLocalHandler, createLocalHandler, } from "./ActionRuntime/Handler/Local/ActionLocalHandler";
 export { ActionServerHandler, createServerHandler, type IActionServerConnectionBinding, type IActionServerHandlerOptions, type TActionChannelFormatMessage, type TActionConnectionEncoding, } from "./ActionRuntime/Handler/Server/ActionServerHandler";
+export { createHibernatableWsServerAdapter, createSecureActionServerHandler, type IHibernatableWsServerAdapter, type IHibernatableWsServerAdapterOptions, type ISecureActionServerHandlerOptions, } from "./ActionRuntime/Handler/Server/createSecureActionServer";
 export * from "./ActionRuntime/RuntimeCoordinate";
 export { EErrId_NiceAction, err_nice_action } from "./errors/err_nice_action";
 export { decodeActionFrame, type IActionFrameDecoder } from "./utils/decodeActionFrame";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -44,9 +44,9 @@
     "build-types": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "@nice-code/common-errors": "0.6.3",
-    "@nice-code/error": "0.6.3",
-    "@nice-code/util": "0.6.3",
+    "@nice-code/common-errors": "0.7.0",
+    "@nice-code/error": "0.7.0",
+    "@nice-code/util": "0.7.0",
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/react-virtual": "^3.13.26",
     "http-status-codes": "^2.3.0",