@rynx-ai/server 0.1.0 → 0.1.9

package/dist/direct-runtime-server.d.ts

@@ -0,0 +1,137 @@
+import type { AddressInfo } from "node:net";
+import { DIRECT_RUNTIME_CONTROL_PATH, type DirectRuntimeClientAuthenticate, type DirectRuntimeChannelRole, type DirectRuntimeServerAccepted, type DirectRuntimeServerHello } from "@rynx-ai/protocol/direct-runtime";
+import { type RuntimeEmulatorSurfaceClientFrame, type RuntimeEmulatorSurfaceOpenFrame, type RuntimeEmulatorSurfaceReadyFrame } from "@rynx-ai/protocol/runtime-emulator-surface";
+import { WebSocket } from "ws";
+import { type AuthenticatedRuntimeSubject, type RemoteRuntimeDispatcher } from "./remote-runtime-dispatcher.js";
+import { type DirectRuntimeBrowserSurfaceHost, type DirectRuntimeBrowserSurfaceServerLimits } from "./direct-runtime-browser-surface-server.js";
+export { DIRECT_RUNTIME_CONTROL_PATH };
+export interface DirectRuntimeAuthenticator {
+    createServerHello(input: {
+        channelBinding: Uint8Array;
+        role: DirectRuntimeChannelRole;
+        signal: AbortSignal;
+    }): DirectRuntimeServerHello | Promise<DirectRuntimeServerHello>;
+    authenticate(input: {
+        channelBinding: Uint8Array;
+        role: DirectRuntimeChannelRole;
+        serverHello: DirectRuntimeServerHello;
+        /**
+         * Exact UTF-8 JSON wire bytes written to this channel. Proofs use the
+         * protocol's canonical encoders; callers must not substitute these bytes.
+         */
+        serverHelloBytes: Uint8Array;
+        clientAuthenticate: DirectRuntimeClientAuthenticate;
+        /**
+         * Exact UTF-8 JSON wire bytes received from this channel. Proofs use the
+         * protocol's canonical encoders; callers must not substitute these bytes.
+         */
+        clientAuthenticateBytes: Uint8Array;
+        signal: AbortSignal;
+    }): DirectRuntimeAuthenticationResult | Promise<DirectRuntimeAuthenticationResult>;
+}
+export interface DirectRuntimeAuthenticationResult {
+    peer: DirectRuntimePeer;
+    accepted: DirectRuntimeServerAccepted;
+}
+/** Direct-binding identity retained only by the transport adapter. */
+export interface DirectRuntimePeer {
+    subject: AuthenticatedRuntimeSubject;
+    clientId: string;
+    grantId: string;
+}
+export interface DirectRuntimeServerLimits {
+    authenticationTimeoutMs: number;
+    maxConnections: number;
+    /** Simultaneous pre-authentication sockets from one real TCP peer address. */
+    maxUnauthenticatedConnectionsPerSource: number;
+    /** Authentication frames admitted from one real TCP peer per fixed window. */
+    maxAuthenticationAttemptsPerSource: number;
+    authenticationAttemptWindowMs: number;
+    /** Hard memory bound for the fixed-window source tracker. */
+    maxTrackedAuthenticationSources: number;
+    /** Simultaneous authenticated channels issued to one grant. */
+    maxConnectionsPerGrant: number;
+    /** Authentication queue depth or authenticated unary RPCs in flight per channel. */
+    maxQueuedFrames: number;
+    /** Request IDs are retained for the connection lifetime; reconnect after this many calls. */
+    maxRequestIds: number;
+    maxBufferedBytes: number;
+    /** Opening or active Remote Session event tails admitted on one authenticated channel. */
+    maxSessionSubscriptions: number;
+    /** Per-subscription application queue, independent of the WebSocket implementation buffer. */
+    maxQueuedSessionEvents: number;
+    maxQueuedSessionEventBytes: number;
+    /** Per-terminal queue; V1 admits one terminal attachment per connection. */
+    maxQueuedTerminalOutputFrames: number;
+    maxQueuedTerminalOutputBytes: number;
+    /** RFC 6455 ping cadence; a peer missing the next heartbeat is terminated. */
+    heartbeatIntervalMs: number;
+    shutdownDeadlineMs: number;
+}
+export interface StartDirectRuntimeServerOptions {
+    host: string;
+    /** Production configuration uses 1-65535; zero is accepted as a test/deployment seam. */
+    port: number;
+    /** Application E2EE identity owned by the daemon, not the transport adapter. */
+    e2ee: {
+        serverPublicKey: string;
+        deriveSharedSecret(clientEphemeralPublicKey: string): Uint8Array;
+    };
+    authenticator: DirectRuntimeAuthenticator;
+    dispatcher: RemoteRuntimeDispatcher;
+    /** Binding-level revocation fence, rechecked before every dispatched RPC. */
+    isPeerActive(peer: DirectRuntimePeer): boolean | Promise<boolean>;
+    connectionHub?: DirectRuntimeConnectionHub;
+    /** Optional additive V3 pixel/input transport on the same Direct listener. */
+    browserSurface?: {
+        host: DirectRuntimeBrowserSurfaceHost;
+        limits?: Partial<Pick<DirectRuntimeBrowserSurfaceServerLimits, "maxQueuedFrames" | "maxBufferedBytes" | "peerLivenessTimeoutMs">>;
+    };
+    /** Session-owned Emulator frames on a dedicated authenticated control connection. */
+    emulatorSurface?: {
+        host: DirectRuntimeEmulatorSurfaceHost;
+    };
+    limits?: Partial<DirectRuntimeServerLimits>;
+    onError?: (error: unknown, context: string) => void;
+}
+export interface DirectRuntimeEmulatorSurfaceAttachment {
+    readonly ready: RuntimeEmulatorSurfaceReadyFrame;
+    capture(): Promise<Uint8Array>;
+    handle(frame: Extract<RuntimeEmulatorSurfaceClientFrame, {
+        type: "emulator.surface.touch";
+    }>): void | Promise<void>;
+    close(): void | Promise<void>;
+}
+export interface DirectRuntimeEmulatorSurfaceHost {
+    open(frame: RuntimeEmulatorSurfaceOpenFrame, context: {
+        peer: DirectRuntimePeer;
+        signal: AbortSignal;
+    }): DirectRuntimeEmulatorSurfaceAttachment | Promise<DirectRuntimeEmulatorSurfaceAttachment>;
+}
+export interface DirectRuntimeServer {
+    readonly connectionHub: DirectRuntimeConnectionHub;
+    readonly listening: boolean;
+    address(): AddressInfo | string | null;
+    shutdown(): Promise<void>;
+}
+interface HubConnection {
+    ws: WebSocket;
+    close(code: number, reason: string): void;
+}
+/** Process-live connection index used to fence grants immediately after revocation. */
+export declare class DirectRuntimeConnectionHub {
+    private readonly connectionsByGrant;
+    private readonly grantByConnection;
+    private readonly revokedGrantIds;
+    /** @internal Called by the Direct adapter after authentication and before acceptance. */
+    register(grantId: string, connection: HubConnection): boolean;
+    /** @internal Atomically fence revocation and enforce a per-grant channel bound. */
+    registerWithinLimit(grantId: string, connection: HubConnection, maxConnections: number): "registered" | "revoked" | "capacity";
+    /** @internal Idempotent adapter cleanup. */
+    unregister(connection: HubConnection): void;
+    /** Mark a grant revoked and immediately close every matching active channel. */
+    revokeGrant(grantId: string, reason?: string): number;
+    get activeConnectionCount(): number;
+}
+/** Start a fail-closed HTTP/WebSocket listener containing only the E2EE Direct route. */
+export declare function startDirectRuntimeServer(options: StartDirectRuntimeServerOptions): Promise<DirectRuntimeServer>;