@mudlet/mudlet-web 0.3.0 → 0.3.1

package/dist-lib/mud/connection/MudClient.d.ts

@@ -67,9 +67,9 @@ export interface MudClientOptions {
     /** Whether the link to the *game server* is TLS-encrypted, reported as the
      *  NEW-ENVIRON `TLS` capability. Defaults to whether `url` is `wss://` — the
      *  correct answer for a direct websocket-mode connection. In proxy (`mud`)
-     *  mode the caller passes `false` explicitly, because a `wss://` proxy URL
-     *  only secures the browser↔proxy hop while the proxy↔MUD telnet socket is
-     *  plaintext (see connectionSecureTransport). */
+     *  mode the caller passes the answer explicitly, because a `wss://` proxy URL
+     *  only secures the browser↔proxy hop: the proxy↔MUD leg is plaintext telnet
+     *  unless the profile enabled TLS (see connectionSecureTransport). */
     secureTransport?: boolean;
     /** Whether to advertise screen-reader use, reported as the MTTS SCREEN
      *  READER bit and the NEW-ENVIRON `SCREEN_READER` capability
@@ -149,6 +149,14 @@ export declare class MudClient {
      *  handshake this session, so a server that re-offers GMCP doesn't make us
      *  announce ourselves twice. Reset on each connect(). */
     private gmcpHelloSent;
+    /** Set when this dial asked the proxy for TLS (`&tls=1` in the URL), so the
+     *  client knows to expect a `tls.established` control frame and to police
+     *  the deadline below. */
+    private readonly tlsRequested;
+    /** True once the proxy confirmed the handshake, or once any game bytes have
+     *  arrived (which can only happen through a working tunnel). */
+    private tlsResolved;
+    private tlsDeadline;
     commandEcho: boolean;
     /** Gates the in-band `!!SOUND(...)` / `!!MUSIC(...)` tag parsing — the tag
      *  bytes are legitimate text on non-MSP MUDs. */
@@ -176,6 +184,11 @@ export declare class MudClient {
     setPromptTimeoutMs(ms: number): void;
     getPromptTimeoutMs(): number;
     connect(): void;
+    /** Stop policing the TLS deadline — the handshake is accounted for. */
+    private resolveTls;
+    /** Decode one proxy control frame. Anything unrecognised is ignored so a
+     *  newer proxy can add message types without breaking older clients. */
+    private handleControlFrame;
     disconnect(): void;
     /** Whether MSP is live on this connection (negotiated, not merely allowed
      *  by the profile config) — gates Mudlet's receiveMSP. */

package/dist-lib/mud/events.d.ts

@@ -2,6 +2,55 @@ import type { AnsiAwareBuffer } from './text/FormatState';
 import type { MspCommand } from './protocol';
 import type { ScriptLogSource } from './MudSession';
 export type SessionStatus = 'disconnected' | 'connecting' | 'connected';
+/** The peer certificate as reported by the proxy. Mirrors the four fields
+ *  Mudlet shows (issuer / issued-to / expiry / serial) plus a little extra for
+ *  diagnostics. All strings, already formatted for display. */
+export interface TlsCertInfo {
+    subject: string;
+    subjectOrg: string;
+    issuer: string;
+    issuerOrg: string;
+    validFrom: string;
+    validTo: string;
+    serial: string;
+    fingerprint: string;
+    altNames: string;
+}
+export interface TlsEstablished {
+    /** Negotiated protocol, e.g. `TLSv1.3`. Empty when the proxy can't report it. */
+    protocol: string;
+    /** Negotiated cipher suite name. Empty when the proxy can't report it. */
+    cipher: string;
+    cert: TlsCertInfo | null;
+    /** False when the proxy runtime cannot inspect certificates at all. */
+    certInspection: boolean;
+    /** Certificate faults tolerated because of the profile's ignore-flags. */
+    acceptedDespite: string[];
+    /** Cert-tolerance options this proxy was asked for but cannot honour. */
+    unsupportedOptions: string[];
+}
+/** What the UI knows about the current connection's TLS state. */
+export type TlsStatus = {
+    kind: 'established';
+    info: TlsEstablished;
+} | {
+    kind: 'error';
+    info: TlsError;
+}
+/** TLS was asked for but nothing came back — see the `tls.timeout` event. */
+ | {
+    kind: 'timeout';
+    host: string;
+    port: number;
+};
+export interface TlsError {
+    /** Primary blocking fault, e.g. `CERT_HAS_EXPIRED`. */
+    code: string;
+    message: string;
+    codes: string[];
+    cert: TlsCertInfo | null;
+    certInspection: boolean;
+}
 /** A pending Mudlet `invokeFileDialog(...)` request. The Lua handler that
  *  called it is suspended (parked coroutine) until `onPick` fires, so the UI
  *  must always resolve it eventually — pass the picked VFS path, or '' for
@@ -26,6 +75,24 @@ export type MudClientEvents = {
     /** The WebSocket subprotocol the server selected from our advertised list
      *  (RFC 6455), or '' if none — only emitted when we advertised any. */
     'client.subprotocol': [protocol: string];
+    /** The proxy completed a TLS handshake with the game and the link is
+     *  carrying decrypted traffic. `cert` is null when the proxy cannot inspect
+     *  certificates (the Cloudflare Worker runtime can't), in which case
+     *  `certInspection` is false. `acceptedDespite` lists any certificate faults
+     *  the profile's ignore-flags waved through — non-empty means encrypted but
+     *  not authenticated. */
+    'tls.established': [info: TlsEstablished];
+    /** The proxy refused the game's certificate, or the TLS handshake failed.
+     *  The connection is closing; `codes` carries every blocking fault. */
+    'tls.error': [info: TlsError];
+    /** TLS was requested but the link produced no evidence of a handshake before
+     *  the deadline. Distinct from `tls.error` because the cause is ambiguous:
+     *  a proxy too old to understand `&tls=1`, or a Cloudflare-Worker-backed
+     *  proxy where a rejected certificate hangs silently instead of reporting. */
+    'tls.timeout': [info: {
+        host: string;
+        port: number;
+    }];
     'gmcp.negotiated': void;
     'msdp.negotiated': void;
     'mssp.negotiated': void;

package/dist-lib/mud/protocol/msspTls.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MSSP-advertised TLS port tracking.
+ *
+ * Mirrors Mudlet's `cTelnet::promptTlsConnectionAvailable` (ctelnet.cpp) —
+ * a server may advertise a secure port through the MSSP `TLS` / `SSL` variable,
+ * and the client offers, once, to switch to it.
+ *
+ * Kept free of React and session plumbing so the decision rules can be tested
+ * directly; the caller supplies the current connection state.
+ */
+/** Per-connection MSSP facts that bear on the TLS offer. */
+export interface MsspTlsFacts {
+    /** The advertised secure port, or 0 when none/unusable. */
+    tlsPort: number;
+    /** MSSP `HOSTNAME`, used to catch an advertisement meant for a different host. */
+    hostName: string;
+}
+export declare function emptyMsspTlsFacts(): MsspTlsFacts;
+/**
+ * Fold one MSSP variable into the accumulated facts.
+ *
+ * `TLS`/`SSL` normally carries a port number, but the values `-1` and `1` are
+ * used by some servers as plain "unsupported"/"supported" booleans. Mudlet
+ * discards both rather than dialling port 1, and so do we.
+ */
+export declare function applyMsspVariable(facts: MsspTlsFacts, name: string, value: string): MsspTlsFacts;
+/** True for a literal IPv4/IPv6 address. A certificate is very unlikely to be
+ *  issued for a bare IP, so Mudlet suppresses the offer in that case rather
+ *  than steering the user into a guaranteed validation failure. */
+export declare function isIpAddress(host: string): boolean;
+export interface TlsOfferState {
+    /** MSSP facts gathered on this connection. */
+    facts: MsspTlsFacts;
+    /** The host this profile actually dialled. */
+    host: string;
+    /** The port currently in use. */
+    port: number;
+    /** Whether this profile is already connecting over TLS. */
+    tlsEnabled: boolean;
+    /** The profile's "remind me about secure connections" preference. */
+    askTlsAvailable: boolean;
+    /** True while an offer is already on screen, so repeats can't stack. */
+    promptInFlight: boolean;
+    /** Only proxy-mode connections can be upgraded: an MSSP TLS port is a raw
+     *  telnet-over-TLS port, which a browser cannot dial directly. */
+    proxyMode: boolean;
+}
+/**
+ * Decide whether to offer the secure-port switch. Mirrors Mudlet's guard set:
+ * a usable advertised port, not already encrypted, the reminder still enabled,
+ * the host not a bare IP, MSSP `HOSTNAME` (when given) matching the host we
+ * dialled, and no offer already pending.
+ */
+export declare function shouldOfferTlsUpgrade(s: TlsOfferState): boolean;

package/dist-lib/mud/protocol/tlsCodes.d.ts

@@ -0,0 +1,4 @@
+export declare function describeCertCode(code: string): string;
+/** Which of Mudlet's three tolerance checkboxes would clear a given fault.
+ *  `all` means only "accept all certificate errors" covers it. */
+export declare function toleranceForCode(code: string): 'expired' | 'selfSigned' | 'all';

package/dist-lib/scripting/IScriptingRuntime.d.ts

@@ -66,6 +66,12 @@ export interface IScriptingRuntime {
      * denyCurrentSend().
      */
     dispatchSendRequest(text: string): boolean;
+    /**
+     * Start a speedwalk between two rooms (Mudlet Host::startSpeedWalk): find
+     * the path and hand it to the mapper package's `doSpeedWalk`. Driven by the
+     * map's double-click-to-walk gesture via WindowManager.startSpeedWalk.
+     */
+    startSpeedWalk(from: number, to: number): void;
     /**
      * Kill every event handler registered by `wrapScript` for the given
      * script id. Called when a script is removed or disabled so its handlers

package/dist-lib/scripting/ScriptingAPI.d.ts

@@ -630,6 +630,14 @@ export declare class ScriptingAPI {
      *  decides the behaviour (send / prompt / open URL); anything else is a
      *  no-op (it was already rejected at parse time). */
     private runHyperlinkUri;
+    /**
+     * Activate an `<a href>` clicked inside a label's rich text — Mudlet's
+     * `TLabel::slot_linkActivated`. Wired onto the LabelManager in the
+     * constructor; see labelLinks.ts for how the schemes differ from the OSC 8
+     * ones {@link runHyperlinkUri} handles (chiefly: a scheme-less href is a Lua
+     * chunk, which is how Geyser packages hang code off a label link).
+     */
+    activateLabelLink(href: string): void;
     /**
      * Build a {@link FormatHyperlink} for an OSC 8 link URI. The scheme decides
      * the behaviour, mirroring Mudlet: `send:` fires the command immediately,

package/dist-lib/scripting/ScriptingEngine.d.ts

@@ -696,7 +696,7 @@ export declare class ScriptingEngine implements EngineHost {
     private performReset;
     /**
      * Resolves once the initial load pass has finished (scripts/aliases/timers/
-     * keys applied, sysLoadEvent fired, triggers compiled). The auto-connect
+     * keys applied, triggers compiled, sysLoadEvent fired). The auto-connect
      * path awaits this so the MUD socket isn't dialed until every handler and
      * trigger is in place. Always resolves — never rejects — so a failed or
      * torn-down load can't leave a profile waiting to connect forever.

package/dist-lib/scripting/lua/LuaRuntime.d.ts

@@ -103,6 +103,14 @@ export declare class LuaRuntime implements IScriptingRuntime {
     private dispatchCb;
     private dispatchCbWithArg;
     private unregisterCb;
+    /**
+     * Mudlet `T2DMap::initiateSpeedWalk` / `Host::startSpeedWalk` — the map's
+     * double-click-to-walk gesture. Pathfinds `from` → `to` (unless the mapper
+     * opted into `mudlet.custom_speedwalk`) and calls the mapper package's
+     * `doSpeedWalk`; see `__mudix_start_speedwalk` in Bridge.lua. Errors inside
+     * the mapper are reported, never thrown at the UI caller.
+     */
+    startSpeedWalk(from: number, to: number): void;
     private execModule;
     private dispatchingEvent;
     private readonly pendingEvents;

package/dist-lib/storage/index.d.ts

@@ -1,4 +1,4 @@
-export { type AppSchema, type MudConnection, type ConnectionMode, type ClientSettings, type ProfileSettings, type MapperSettings, type MapInfoBgColor, type ProtocolSettings, type BooleanProtocolKey, type Theme, type OutputFontSource, APP_DEFAULTS, PROFILE_DEFAULTS, MAPPER_DEFAULTS, MAP_INFO_BG_DEFAULT, PROTOCOL_DEFAULTS, WS_SUBPROTOCOL_CHOICES, DEFAULT_PROXY_URL, connectionUrl, connectionDisplayAddr, connectionSecureTransport, selectProfileField } from './schema';
+export { type AppSchema, type MudConnection, type ConnectionMode, type ClientSettings, type ProfileSettings, type MapperSettings, type MapInfoBgColor, type ProtocolSettings, type BooleanProtocolKey, type Theme, type OutputFontSource, APP_DEFAULTS, PROFILE_DEFAULTS, MAPPER_DEFAULTS, MAP_INFO_BG_DEFAULT, PROTOCOL_DEFAULTS, WS_SUBPROTOCOL_CHOICES, DEFAULT_PROXY_URL, connectionUrl, connectionDisplayAddr, connectionSecureTransport, effectiveProxyUrl, proxyCanInspectCertificates, selectProfileField } from './schema';
 export { useAppStore } from './appStore';
 export { initCrossTabSync } from './crossTabSync';
 export { ConnectionIdContext, useConnectionId, useProfileField, useClientField, useEffectiveTheme } from './hooks';

package/dist-lib/storage/schema.d.ts

@@ -44,6 +44,28 @@ export interface MudConnection {
      *  already ship them — Mudlet installs those only into brand-new profiles, so
      *  their absence in an imported profile is a real choice, not a gap to fill. */
     mudletImported?: boolean;
+    /** Connect to the game over TLS — Mudlet's `mSslTsl` / the connection
+     *  dialog's "secure connection" checkbox. Meaningful in `mud` (proxy) mode
+     *  only: the browser cannot wrap a raw socket itself, so the proxy performs
+     *  the handshake on our behalf (`&tls=1`). In `websocket` mode the URL
+     *  scheme already decides it, so this flag is ignored there. */
+    tls?: boolean;
+    /** Tolerate an expired peer certificate (Mudlet's `mSslIgnoreExpired`). */
+    sslIgnoreExpired?: boolean;
+    /** Tolerate a self-signed peer certificate (Mudlet's `mSslIgnoreSelfSigned`). */
+    sslIgnoreSelfSigned?: boolean;
+    /** Tolerate *every* certificate fault, hostname mismatch included — this
+     *  gives up the authentication half of TLS and leaves only encryption
+     *  (Mudlet's `mSslIgnoreAll`, labelled "unsecure" in its UI).
+     *
+     *  ⚠ All three are honoured only by the Node proxy. The Cloudflare Worker
+     *  runtime's `connect()` exposes no way to inspect or override certificate
+     *  validation, so a worker-backed profile silently ignores them. */
+    sslIgnoreAll?: boolean;
+    /** The plaintext port in use before an MSSP-advertised TLS upgrade, kept so
+     *  a failed upgrade can be reverted in one click. Cleared once a secure
+     *  connection has actually worked. */
+    preTlsPort?: number;
     /** Free-text profile description (Mudlet's profile "description" field, read/
      *  written by getProfileInformation / setProfileInformation /
      *  clearProfileInformation). Lives on the connection record — not the VFS-
@@ -105,6 +127,12 @@ export interface ProfileSettings {
      *  installed automatically). Disable to ignore those requests. Per-profile
      *  so each MUD is trusted independently. */
     allowMudPackageInstall?: boolean;
+    /** When true (default), a server that advertises a TLS port via MSSP prompts
+     *  once to switch to it. Declining sets this false so the offer never
+     *  reappears for this profile. Mudlet calls it `mAskTlsAvailable`
+     *  ("Allow secure connection reminder"), settable from Lua via
+     *  `setProfileConfig("askTlsAvailable", …)`. */
+    askTlsAvailable?: boolean;
     showTimestamps: boolean;
     fontSize: number;
     outputBackground: string;
@@ -626,13 +654,31 @@ export declare const APP_DEFAULTS: AppSchema;
  */
 export declare function selectProfileField<K extends keyof ProfileSettings>(s: Pick<AppSchema, 'connectionProfile'>, connectionId: string | null, key: K): ProfileSettings[K];
 export declare function connectionUrl(c: MudConnection, userProxyUrl?: string): string;
+/** The proxy a `mud`-mode connection will actually dial, applying the same
+ *  precedence as {@link connectionUrl}: per-connection > user's own > brand >
+ *  built-in default. */
+export declare function effectiveProxyUrl(c: MudConnection, userProxyUrl?: string): string;
+/**
+ * Whether a proxy can inspect the game's certificate — and therefore whether
+ * the "accept expired / self-signed / all" options mean anything.
+ *
+ * Only the Node proxy can: it uses `tls.connect` and reads the peer certificate.
+ * A Cloudflare Worker cannot, because `cloudflare:sockets` `connect()` exposes
+ * no certificate and no way to waive a validation failure — the options would be
+ * silently ignored, so the UI disables them instead of pretending.
+ *
+ * Recognised by the `workers.dev` hostname, which covers the built-in default
+ * proxy and anything deployed from `worker/`. A Worker on a custom domain can't
+ * be told apart from a Node proxy up front; that case is corrected at runtime by
+ * the `certInspection: false` flag the proxy reports on `tls.established`.
+ */
+export declare function proxyCanInspectCertificates(proxyUrl: string): boolean;
 export declare function connectionDisplayAddr(c: MudConnection): string;
 /** Whether the connection's link to the *game server* is TLS-encrypted — the
  *  signal reported as the NEW-ENVIRON `TLS` variable. In `websocket` mode the
  *  browser connects straight to the game, so a `wss://` URL is end-to-end TLS.
- *  In `mud` (proxy) mode the browser↔proxy hop may be `wss://`, but the proxy
- *  reaches the MUD over a raw TCP telnet socket (`net.connect`, no upstream
- *  TLS) — so the server's inbound connection is always plaintext and this is
- *  false regardless of the proxy URL scheme. */
+ *  In `mud` (proxy) mode the browser↔proxy hop being `wss://` says nothing about
+ *  the proxy↔game hop: that leg is a plaintext telnet socket unless `tls` is set,
+ *  which makes the proxy perform a TLS handshake with the game instead. */
 export declare function connectionSecureTransport(c: MudConnection): boolean;
 export {};