omnyshell_node library

Classes

ActiveSessionDetachRequest: Client → Hub: detach an active (attached) session on nodeId from another connection — e.g. when a full-screen program owns the original terminal. sessionRef is an id/short-id/prefix, or empty to target the caller's sole active session. Correlated by requestId.
ActiveSessionDetachResponse: Hub → Client: the result of an active-session detach. Correlated by requestId.
Authenticator: Validates a Credential and resolves it to a Principal.
AuthFail: Failed authentication.
AuthOk: Successful authentication, carrying the resolved identity and a session token bound to this connection.
Authorizer: Decides whether an authenticated Principal may open a session on a node.
AuthRequest: A login attempt presenting a credential.
CertGenerator: Generates the TLS certificate material an OmnyShell Hub needs to run.
CertificateIdentity: Extracts a stable public-key identity from an X.509 certificate.
Channel: One logical, bidirectional stream multiplexed over a connection.
ChannelClose: Tear down a channel.
ChannelEof: Half-close a stream (typically stdin) on the channel.
ChannelExit: Node → Client: the process exited.
ChannelId: A logical channel identifier, scoped to a single physical connection.
ChannelMultiplexer: Multiplexes logical Channels over a single OmnyShellConnection.
ChannelResize: Resize the terminal of an interactive session.
ChannelSignal: Deliver a POSIX signal to the session's process.
ChannelWindow: Backpressure credit grant for a stream on a channel.
Clock: Time source used throughout OmnyShell so tests can fix now.
ControlFrame: A control message frame (carried as a WebSocket text frame).
ControlMessage: Base class for every structured control message.
Credential: A credential presented during the authentication handshake.
CredentialProvider: Produces the AuthRequest a node or client sends in response to the Hub's challenge hello.
CredentialStore: On-disk store of Hub logins, keyed by Hub URL, with a remembered default.
DataFrame: A binary stream-data frame (carried as a WebSocket binary frame) with a fixed 10-byte header followed by the raw payload bytes.
DetachedSessionInfo: A user-facing view of a detached session living in a node's in-memory registry, as returned by the list API and relayed through the Hub.
DetachedSessionKillRequest: Client → Hub: terminate the caller's detached session sessionRef (an unambiguous id or prefix) on nodeId. Correlated by requestId.
DetachedSessionKillResponse: Hub → Client: the result of a detached-session kill. Correlated by requestId.
DetachedSessionsRequest: Client → Hub: list the caller's detached sessions on nodeId. Correlated to the response by requestId (a connection-level request/response RPC).
DetachedSessionsResponse: Hub → Client: the caller's detached sessions. Correlated by requestId.
Ed25519PublicKey: An Ed25519 public key, used to identify users and nodes in an authorized_keys-style trust store. Equality is by key bytes.
ErrorCodes: Stable, machine-readable error codes carried in error control messages and surfaced on OmnyShellExceptions.
FrameCodec: Encodes and decodes OmnyShellFrames to and from WebSocket events.
GeneratedCertificates: The paths of the TLS files produced by CertGenerator.generate.
Hello: First frame after the WebSocket upgrade. The Hub sends hello with a single-use nonce; the peer replies with its role and capabilities.
MachineId: Reads a stable, per-machine identifier provided by the operating system.
NodeActiveSessionDetach: Hub → Node: detach the principal's active session sessionRef.
NodeActiveSessionDetachResponse: Node → Hub: the result of an active-session detach. Correlated by requestId.
NodeCapabilities: What a node can do, advertised to the Hub after registration and relayed to clients during discovery.
NodeCapabilitiesMessage: Node → Hub: advertises capabilities after registration.
NodeConfig: Configuration for a NodeRuntime.
NodeDescriptor: A node's public description as registered with the Hub and returned by discovery (nodes list). Combines identity, platform, operator labels and advertised capabilities.
NodeDetachedSessionKillRequest: Hub → Node: terminate the principal's detached session sessionRef.
NodeDetachedSessionKillResponse: Node → Hub: the result of a detached-session kill. Correlated by requestId.
NodeDetachedSessionsRequest: Hub → Node: list the principal's detached sessions. Correlated by requestId.
NodeDetachedSessionsResponse: Node → Hub: the principal's detached sessions. Correlated by requestId.
NodeHeartbeat: Node → Hub: periodic liveness signal with a monotonic sequence number.
NodeHeartbeatAck: Hub → Node: acknowledges a heartbeat.
NodeId: Stable identity of a node, used by clients to address it (instead of a host:port). Equality is by value.
NodeListRequest: Client → Hub: requests the list of nodes the client may see.
NodeListResponse: Hub → Client: the discovered nodes.
NodeProfile: A node's environment profile, persisted at ~/.omnyshell/profile.yaml and applied as the baseEnvironment of every shell/exec session the node serves.
NodeRegister: Node → Hub: registers the node's identity and platform.
NodeRegistered: Hub → Node: confirms registration.
NodeRuntime: An embeddable OmnyShell node: maintains a secure connection to the Hub, registers, advertises capabilities, and serves sessions, reconnecting with backoff if the connection drops.
NodeSessionDetach: Hub → Node: detach the session on the node-side channel, on behalf of principal. Mirrors SessionDetachRequest across the relay.
NodeSessionDetached: Node → Hub: the session was detached and now lives in the node registry.
NodeSessionOpen: Hub → Node: instructs the node to start a session on a node-side channel.
NodeSessionOpened: Node → Hub: the node accepted and started the session.
NodeSessionRejected: Node → Hub: the node refused the session.
NodeSessionScreenRequest: Hub → Node: fetch the current screen snapshot of the principal's session sessionRef. Correlated by requestId.
NodeSessionScreenResponse: Node → Hub: the current screen snapshot of a session. The replayable bytes (the same a resume would paint) are base64-encoded in screenBase64. Correlated by requestId.
NodeTunnelConnect: Hub → exposer (node or client): a public connection arrived; adopt channel, dial targetHost:targetPort, and bridge bytes. Reply with NodeTunnelConnected or NodeTunnelConnectFailed.
NodeTunnelConnected: Exposer → Hub: the target was dialed; the Hub may relay bytes on channel.
NodeTunnelConnectFailed: Exposer → Hub: the target dial failed; the Hub closes the public socket.
OmnyShellConnection: A duplex, frame-oriented link between two OmnyShell peers.
OmnyShellFrame: A decoded unit travelling over a connection: either a structured control message (ControlFrame) or a binary stream payload (DataFrame).
OmnyUid: A deterministic, globally-stable identifier for a node or a hub.
PathDiff: The difference between an old and new PATH, for the confirmation prompt.
Ping: Application-level keepalive request, used to measure round-trip latency and detect half-open connections.
PlatformInfo: Describes the operating system and architecture a node runs on, advertised to clients during discovery and shown by the :info local command.
Pong: Reply to a Ping.
Principal: An authenticated identity, as resolved by an Authenticator.
PrincipalId: Identity of an authenticated principal (a user or a node account) as known to the Hub. Equality is by value.
ProcessShellBackend: A ShellBackend that runs commands and interactive shells as OS processes.
ProcessShellSession: A ShellSession backed by an OS process started with Process.start.
ProtocolError: A connection- or channel-level error.
PtySpec: Requested pseudo-terminal geometry for an interactive shell.
PublicKeyCredential: An Ed25519 public-key credential: the client proves possession of the private key by signing the connection challenge.
PublicKeyCredentialProvider: A CredentialProvider that signs the connection nonce with an Ed25519 private key.
ReconnectPolicy: Computes reconnect delays with exponential backoff and jitter.
RoleBasedAuthorizer: A role-based Authorizer with a small, predictable policy:
ScriptPtyShellBackend: A ShellBackend that runs interactive shells on a real pseudo-terminal allocated by the system script(1) utility — without dart:ffi or any native library.
ScriptPtyShellSession: A ShellSession backed by a real pseudo-terminal allocated by the system script(1) utility, which runs as an ordinary child Process.
Session: A domain view of a brokered session: who opened it, on which node, in what mode, and its current state and exit code.
SessionDetached: Hub → Client: the session was detached; resume it later by shortId.
SessionDetachRequest: Client → Hub: detach the live session on channel, keeping the node-side PTY/shell/processes running. Optional timeoutSeconds schedules automatic cleanup; null keeps the session indefinitely.
SessionId: Unique identity of a brokered session, minted by the Hub when a session is opened. Equality is by value.
SessionOpen: Client → Hub: opens a session on a node over a new client channel.
SessionOpened: Hub → Client: the session is open.
SessionRejected: Hub → Client (or Node → Hub via NodeSessionRejected): the session could not be opened.
SessionScreenRequest: Client → Hub: fetch the current screen snapshot of the caller's session sessionRef (active or detached) on nodeId, without attaching to it. Correlated by requestId.
SessionScreenResponse: Hub → Client: the current screen snapshot of a session. Correlated by requestId.
ShellBackend: Starts ShellSessions on a node in response to authorized session opens.
ShellRequest: A request to start a process or interactive shell on a node.
ShellSession: A running process or shell on the node, with byte streams wired to the session channel.
StoredSession: A persisted login to a single Hub.
SystemClock: The default Clock, backed by the system wall clock (UTC).
TokenCredential: A bearer-token credential, validated against a token store. Relies on TLS for secrecy in transit.
TokenCredentialProvider: A CredentialProvider that presents a bearer token.
TunnelCloseRequest: Client → Hub: close the caller's tunnel tunnelRef (a full id or unambiguous prefix). Correlated by requestId.
TunnelCloseResponse: Hub → Client: the result of a tunnel close. Correlated by requestId.
TunnelInfo: A user-facing view of an active TCP tunnel held by the Hub, as returned by the list API and relayed to the owning client.
TunnelListRequest: Client → Hub: list the caller's active tunnels. Correlated by requestId.
TunnelListResponse: Hub → Client: the caller's active tunnels. Correlated by requestId.
TunnelOpened: Hub → Client: the tunnel is open and listening. Correlated by requestId.
TunnelOpenRequest: Client → Hub: open a tunnel that exposes targetHost:targetPort (reachable by nodeId, or the requesting client's own machine when nodeId is the @local sentinel) on a public Hub port. When publicPort is set the Hub validates it against its configured range; otherwise the Hub allocates a free port in range. Correlated by requestId.
TunnelRejected: Hub → Client: the tunnel was refused. Correlated by requestId.
UidComputer: Computes deterministic OmnyUids from identity material.
UidResolution: The outcome of resolving an entity's UID against its persisted value.
UidStore: Persists an entity's UID under ~/.omnyshell/<fileName> and detects changes.
WindowsTaskService: Runs the Hub/Node as a Windows Task Scheduler task instead of a Service Control Manager service.

Enums

DataOpcode: The stream a binary data frame belongs to, encoded as the msgType byte of the data-frame header.
NodeState: The lifecycle state of a NodeRuntime.
SessionMode: How a session runs on the node.
SessionState: Lifecycle state of a session as tracked by the Hub.
ShellFamily: The command-language family of a node's interactive shell.

Constants

kMinProtocolVersion → const int: The lowest protocol version this build can interoperate with.
kProtocolVersion → const int: The wire protocol version implemented by this package.
omnyShellVersion → const String: The canonical OmnyShell package version (kept in sync with pubspec.yaml).
xmlBasename → const String: The filename written into the temp dir before schtasks /Create /XML.

Functions

buildTaskXml(ServiceDescriptor d, {required String logPath, String? currentUser}) → String: Builds the Task Scheduler definition XML for d.
captureLoginPath({required String shell, Duration timeout = const Duration(seconds: 10)}) → Future<String?>: Runs shell as a login+interactive shell and returns the PATH it exports, or null on Windows, when script/the shell fails, on timeout, or when the markers are missing.
createArgs(String tn, String xmlPath, {bool force = false}) → List<String>: schtasks argument vector that imports xmlPath as task tn.
deleteArgs(String tn) → List<String>: schtasks argument vector to delete task tn.
encodeUtf16Le(String s) → List<int>: Encodes s as UTF-16 little-endian with a leading BOM — the encoding schtasks /Create /XML requires (a UTF-8 file is rejected with "cannot switch encoding").
endArgs(String tn) → List<String>: schtasks argument vector to stop task tn.
isProtocolCompatible(int remoteVersion, {int? remoteMin}) → bool: Whether a peer advertising remoteVersion (with optional remoteMin) is compatible with this build.
newId() → String: Generates a new globally-unique identifier (UUID v4).
newSecureToken([int byteLength = 32]) → String: Returns byteLength cryptographically secure random bytes encoded as a URL-safe, unpadded base64 string.
parseStatus(String output) → String: Parses the Status: field out of schtasks /Query /FO LIST /V output.
pathDiff(String? oldPath, String newPath) → PathDiff: Computes the PathDiff between oldPath (may be null) and newPath.
queryArgs(String tn) → List<String>: schtasks argument vector to query task tn in verbose list form.
rcFileFor(String shell) → String: Best-effort rc file path shown to the user for shell (display only).
runArgs(String tn) → List<String>: schtasks argument vector to start task tn on demand.
shortId(String id, [int length = 8]) → String: Derives a short, human-friendly handle from a full id.
taskName(String role) → String: The Task Scheduler task name (folder + leaf) for role, e.g. \OmnyShell\node.
uniquePath(String path) → String: Returns path with empty and duplicate entries removed, keeping the first occurrence of each (order preserved). Used so the exported profile PATH never carries repeats a login shell may have accumulated.

Typedefs

ControlDecoder = ControlMessage Function(int? channelId, Map<String, dynamic> data): Decodes a control-message payload (the envelope d) for a registered type.
OmnyShellNode = NodeRuntime: Friendly alias for NodeRuntime, the embeddable OmnyShell node.
ProcessRunner = Future<ProcessResult> Function(String executable, List<String> arguments): Runs an external process; injectable so command construction can be unit tested without invoking schtasks/sc.

Exceptions / Errors

AuthException: Authentication failed: credentials missing, malformed or rejected.
AuthorizationException: The authenticated principal is not permitted to perform the action.
CertGeneratorException: Thrown when certificate generation cannot complete.
ChannelException: A logical channel was closed or referenced after teardown.
NodeUnavailableException: The requested node is unknown or offline.
OmnyShellException: Base type for every expected, classified failure raised by OmnyShell.
OmnyShellTimeoutException: An operation exceeded its deadline.
ProtocolException: A frame could not be decoded, or a message violated the protocol.
SessionRejectedException: A session could not be opened (rejected by the Hub or node).
TransportException: The underlying transport failed or closed unexpectedly.
TunnelRejectedException: A tunnel could not be opened (rejected by the Hub).
WindowsTaskException: Thrown when a schtasks lifecycle operation fails.

omnyshell_node library

Classes

Enums

Constants

Functions

Typedefs

Exceptions / Errors

omnyshell package

omnyshell_node library