@mudlet/mudlet-web 0.5.0 → 1.0.1

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

@@ -0,0 +1,128 @@
+/**
+ * The client-driven GMCP `Char.Login` v2 OAuth flow, for a browser.
+ *
+ * Port of Mudlet's `OAuthClientFlow` (development branch). When the game is its
+ * own OpenID Provider it advertises a discovery document and a `client_id`; we
+ * fetch the document, build the provider's authorization URL with a PKCE (S256)
+ * challenge, wait for the provider to redirect back with an authorization code,
+ * and hand `{code, code_verifier, redirect_uri, nonce}` to the caller, which
+ * sends it to the game as `Char.Login.AuthCode`. The token exchange itself stays
+ * on the game server.
+ *
+ * **The redirect is where a browser has to differ.** Desktop Mudlet listens on
+ * `http://127.0.0.1:<random port>/` — an RFC 8252 loopback redirect, which a
+ * provider registers once and accepts on any port. A web page cannot listen on a
+ * socket, so our redirect is a real page on our own origin,
+ * `oauth-callback.html` beside the app (or a branded build's
+ * `oauthRedirectUrl`). The game's provider has to have registered that address
+ * for its `client_id`, next to Mudlet's loopback one. The page reports the
+ * provider's answer over a same-origin `BroadcastChannel`, which works whether
+ * the sign-in ran in a popup, a tab or a tab the player opened by hand, and
+ * survives a provider that severs `window.opener` with COOP.
+ *
+ * Opening the authorization URL is the caller's job — a browser only lets a
+ * page open one from a user gesture, so it becomes a button — exactly as
+ * Mudlet leaves launching the browser to `GMCPAuthenticator`.
+ */
+/** One deadline covers the whole flow — discovery, the player's sign-in, the
+ *  redirect — so an abandoned attempt cannot keep listening for ever. */
+export declare const OAUTH_FLOW_TIMEOUT_MS: number;
+/** The channel `oauth-callback.html` reports on. Keep in step with that page. */
+export declare const OAUTH_CALLBACK_CHANNEL = "mudlet-web-oauth";
+/** What `oauth-callback.html` posts: the redirect's parameters, verbatim. */
+export interface OAuthCallbackMessage {
+    type: 'callback';
+    state?: string;
+    code?: string;
+    error?: string;
+}
+/** What the app answers so the page can tell the player how it went. */
+export interface OAuthCallbackAck {
+    type: 'ack';
+    state: string;
+    ok: boolean;
+}
+/** 32 random bytes, base64url without padding: a 43-character verifier, the
+ *  RFC 7636 minimum, from the required unreserved character set. */
+export declare function generateCodeVerifier(): string;
+/** RFC 7636 S256: base64url(SHA-256(ASCII(verifier))). */
+export declare function codeChallengeS256(codeVerifier: string): Promise<string>;
+/**
+ * OAuth endpoints must be https; plain http is permitted solely for loopback
+ * hosts, so self-hosted and test setups work without certificates. Mudlet's
+ * `acceptableEndpointUrl`.
+ */
+export declare function acceptableEndpointUrl(raw: string): boolean;
+export declare function buildAuthorizationUrl(authorizationEndpoint: string, clientId: string, scopes: string[], redirectUri: string, state: string, codeChallenge: string, nonce?: string): string;
+/**
+ * The redirect URI this build asks providers to send the player back to: a
+ * branded build's `oauthRedirectUrl`, else `oauth-callback.html` beside the
+ * app. It must be same-origin with the app — the callback reports over a
+ * same-origin `BroadcastChannel` — and is what each game's provider has to
+ * register for its `client_id`.
+ */
+export declare function defaultOAuthRedirectUri(): string | null;
+/** Whether this page can run the flow at all: WebCrypto (a secure context) for
+ *  PKCE, and `BroadcastChannel` to hear the callback. */
+export declare function clientOAuthSupported(): boolean;
+/** What a successful flow hands back — exactly the `Char.Login.AuthCode` body,
+ *  less the common fields. */
+export interface OAuthAuthorization {
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+    nonce?: string;
+}
+/**
+ * Which half failed. `setup` is everything before the player is involved —
+ * discovery (commonly a provider that serves its discovery document without
+ * CORS headers, which only a browser trips over), a bad endpoint — and the
+ * caller can still fall back to the game's own sign-in. `signin` is the player's
+ * attempt itself: the provider refused, the state did not match, or it timed
+ * out.
+ */
+export type OAuthFailureStage = 'setup' | 'signin';
+/** The slice of BroadcastChannel the flow uses; injectable for tests. */
+export interface OAuthChannel {
+    onmessage: ((ev: MessageEvent) => void) | null;
+    postMessage(message: unknown): void;
+    close(): void;
+}
+export interface OAuthClientFlowOptions {
+    discoveryUrl: string;
+    clientId: string;
+    scopes: string[];
+    nonceRequired: boolean;
+    redirectUri: string;
+    onAuthorizationUrl: (url: string) => void;
+    onCaptured: (authorization: OAuthAuthorization) => void;
+    onFailed: (logDetail: string, stage: OAuthFailureStage) => void;
+    fetch?: typeof fetch;
+    openChannel?: (name: string) => OAuthChannel;
+    timeoutMs?: number;
+}
+/**
+ * Single-use: create a fresh flow for each sign-in attempt. Reaches exactly one
+ * terminal outcome — captured, failed or aborted — after which every late
+ * callback, timer or message is ignored.
+ */
+export declare class OAuthClientFlow {
+    private readonly opts;
+    private started;
+    private completed;
+    private channel;
+    private timer;
+    private abortController;
+    private codeVerifier;
+    private state;
+    private nonce;
+    constructor(opts: OAuthClientFlowOptions);
+    get done(): boolean;
+    start(): void;
+    abort(): void;
+    private discover;
+    private handleCallback;
+    private ack;
+    private fail;
+    private cleanup;
+}

package/dist-lib/mud/protocol/qtCodePages.generated.d.ts

@@ -0,0 +1 @@
+export declare const QT_CODE_PAGES: Readonly<Record<string, string>>;

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

@@ -1,4 +1,41 @@
 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';
+export declare function isCertificateFault(code: string): boolean;
+/** Which of Mudlet's three tolerance checkboxes would clear a given fault, or
+ *  null when no checkbox can — the fault is not about a certificate. */
+export declare function toleranceForCode(code: string): 'expired' | 'selfSigned' | 'all' | null;
+/** What the UI needs to know about a failed handshake, in prose. */
+export interface TlsFailureExplanation {
+    /** What went wrong, as one sentence. */
+    summary: string;
+    /** What to do about it, or null when nothing honest can be suggested.
+     *  Never names a control that isn't rendered. */
+    remedy: string | null;
+    /** True when the fault is about the peer's certificate at all. */
+    certificateFault: boolean;
+}
+/**
+ * Turn a `tls.error` into a diagnosis and a remedy that exists.
+ *
+ * Both used to be composed from the certificate vocabulary regardless of what
+ * failed: connecting with TLS to a plaintext port was reported as a certificate
+ * refusal and the user was told to tick "Accept all certificate errors" in
+ * Settings → Network — a control that is not rendered on the default
+ * Cloudflare-Worker proxy (`proxyCanInspectCertificates` is false for it and
+ * for every `*.workers.dev` host, so that panel says "Certificate options
+ * unavailable" instead), and that would not have helped if it were.
+ *
+ * Desktop Mudlet reports the underlying socket/SSL error verbatim and only
+ * offers the ignore-certificate settings when they apply; its answer to a
+ * `QAbstractSocket::SslHandshakeFailedError` is "Secure connections not
+ * supported by this game on this port; try turning the option off"
+ * (`src/ctelnet.cpp:865`). This is that, phrased for the controls this client
+ * actually has.
+ */
+export declare function describeTlsFailure(info: {
+    code: string;
+    message?: string;
+    codes?: string[];
+    /** False when the proxy runtime cannot inspect certificates at all, and so
+     *  cannot offer — or render — the tolerance options. */
+    certInspection?: boolean;
+}): TlsFailureExplanation;

package/dist-lib/mud/replay/ReplayPlayer.d.ts

@@ -9,6 +9,19 @@ export interface ReplayPlayerCallbacks {
     feed: (data: string) => void;
     /** Fired once, after the last chunk has been delivered. Not fired on abort. */
     onDone: () => void;
+    /**
+     * Reads a chunk again as it comes up, from the file as it is now. Mudlet
+     * reads its replay file a chunk at a time while it plays
+     * (cTelnet::loadReplayChunk), so the chunks parsed at load time are only
+     * what the file held THEN. Returning null says the chunk can no longer be
+     * read — a header turned negative or too long — and the replay ends there
+     * through {@link onCorrupt}. Left out, the parsed chunks are played as they
+     * are (a replay with no file behind it).
+     */
+    reread?: (chunk: ReplayChunk, index: number) => ReplayChunk | null;
+    /** Fired once, instead of onDone, when {@link reread} found a chunk that
+     *  will not read. Nothing after it is played. */
+    onCorrupt?: () => void;
 }
 /**
  * Plays parsed replay chunks back on their recorded timeline: each chunk is
@@ -17,11 +30,13 @@ export interface ReplayPlayerCallbacks {
  * they did live.
  */
 export declare class ReplayPlayer {
-    private readonly chunks;
     private readonly callbacks;
     private timer;
     private index;
     private finished;
+    /** Our own copy: {@link ReplayPlayerCallbacks.reread} replaces entries as
+     *  they come up, and the caller's array is not ours to write. */
+    private readonly chunks;
     constructor(chunks: ReplayChunk[], callbacks: ReplayPlayerCallbacks);
     start(): void;
     /** Stop playback and drop any pending chunk. Idempotent; onDone is not

package/dist-lib/mud/replay/replayFormat.d.ts

@@ -5,7 +5,7 @@
  * The on-disk layout is a bare sequence of chunk records with no header:
  *
  *     int32 BE  offsetMs   milliseconds elapsed since the previous chunk
- *     int32 BE  length     payload byte count (1..REPLAY_MAX_CHUNK)
+ *     int32 BE  length     payload byte count (0..REPLAY_MAX_CHUNK)
  *     bytes     payload    the network data verbatim — post-MCCP-decompression,
  *                          pre-telnet-parsing, IAC sequences and all
  *
@@ -21,7 +21,14 @@ export interface ReplayChunk {
     offsetMs: number;
     /** Raw telnet bytes as received post-MCCP. */
     data: Uint8Array;
+    /** Byte offset of this chunk's header in the file it was parsed from. Set
+     *  by {@link parseReplayLayout}, so playback can read the chunk again from
+     *  disk when it comes due — see readReplayChunkAt. */
+    position?: number;
 }
+/** The width of the delay field: 4 in the original layout, 8 in the PR #4400
+ *  "modified format". */
+export type ReplayOffsetSize = 4 | 8;
 /** Mudlet's replay read buffer size (cTelnet BUFFER_SIZE). A record whose
  *  length field exceeds this is treated as corrupt by Mudlet's loader, so the
  *  encoder splits bigger payloads into continuation records (offset 0). */
@@ -35,13 +42,33 @@ export declare function replayBytesToLatin1(bytes: Uint8Array): string;
 /** Serialize chunks to the original (current-Mudlet) replay format. Payloads
  *  larger than {@link REPLAY_MAX_CHUNK} are split into continuation records
  *  with a 0ms offset so Mudlet itself can read the file back. Empty payloads
- *  are dropped — Mudlet's loader treats a 0-length record as corruption. */
+ *  are dropped — there is nothing in them to play. */
 export declare function encodeReplay(chunks: ReplayChunk[]): Uint8Array;
 /** Parse a replay file, auto-detecting the original (4-byte offset) vs the
  *  modified (8-byte offset, PR #4400 era) layout the way Mudlet's
  *  testReadReplayFile does: trial-parse original first, fall back to modified.
  *  Returns null when the data is readable as neither — "seems to be corrupt". */
 export declare function parseReplay(bytes: Uint8Array): ReplayChunk[] | null;
+/** {@link parseReplay}, also saying which layout the file turned out to be in,
+ *  which is what reading a chunk back from disk at play time needs to know. */
+export declare function parseReplayLayout(bytes: Uint8Array): {
+    chunks: ReplayChunk[];
+    offsetSize: ReplayOffsetSize;
+} | null;
+/**
+ * The chunk whose header starts at `position`, read again from the file as it
+ * is NOW — or null when that header has stopped being a usable one.
+ *
+ * Mudlet vets a replay file once, when it is loaded, and then reads it a chunk
+ * at a time as it plays (cTelnet::loadReplayChunk), so a file that changes
+ * underneath a running replay is played as it has become — and a chunk header
+ * that went bad since is where the replay ends ("seems to be corrupt"), rather
+ * than a negative delay arming a timer that never fires and leaves the replay
+ * stuck as running. `readAt` reads up to `length` bytes from `position`; a
+ * payload cut short by the end of the file is played as far as it goes, as
+ * QDataStream::readRawData returns what it got.
+ */
+export declare function readReplayChunkAt(readAt: (position: number, length: number) => Uint8Array, position: number, offsetSize: ReplayOffsetSize): ReplayChunk | null;
 /** Total recorded duration in milliseconds (sum of chunk offsets). */
 export declare function replayDurationMs(chunks: ReplayChunk[]): number;
 /** Mudlet-style replay file name for a recording finished at `date`: