serverless-ircd 0.9.0 → 0.11.0

package/apps/local-cli/src/server.ts

@@ -33,20 +33,22 @@ import { randomUUID } from 'node:crypto';
 import { type Server, type Socket, createServer } from 'node:net';
 import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
 import {
-  type AccountStore,
   type AdmissionConfig,
   type ChanName,
   type ConnectionState,
   ConsoleLogger,
-  InMemoryAccountStore,
   InMemoryMessageStore,
   InMemoryNickHistoryStore,
+  InMemoryServicesStore,
   LogLevel,
   type Logger,
   type MessageStore,
   type NickHistoryStore,
+  type OperCred,
   type RawLine,
   type ServerConfig,
+  type ServicesStore,
+  SystemClock,
   WS_SUBPROTO_BINARY,
   WS_SUBPROTO_TEXT,
   type WsFrameMode,
@@ -168,10 +170,11 @@ export interface LocalServerConfig {
    */
   historyMaxPerChannel?: number;
   /**
-   * SASL PLAIN account credentials. When non-empty the server seeds an
-   * in-memory {@link AccountStore} so `AUTHENTICATE PLAIN` succeeds for the
-   * listed accounts. When omitted/empty, SASL account verification is
-   * disabled (`ctx.accounts` undefined → `904 ERR_SASLFAIL`).
+   * SASL PLAIN account credentials. Seeded into the in-memory
+   * {@link ServicesStore} at boot so `AUTHENTICATE PLAIN`, `PASS
+   * <nick>:<password>`, and NickServ `IDENTIFY` all verify against the
+   * listed accounts. Empty array (the default) still binds a services
+   * store — NickServ REGISTER creates accounts at runtime.
    */
   saslAccounts?: Array<{ username: string; password: string }>;
   /**
@@ -180,8 +183,15 @@ export interface LocalServerConfig {
    * like `REHASH` are unreachable; supply a non-empty list to let a client
    * oper up. Threaded straight through to the reducer-facing
    * {@link ServerConfig} via the shared schema.
+   *
+   * Each entry is EITHER the at-rest hashed form
+   * `{user, salt, hash}` (recommended — generate via
+   * `tools/hash-oper-cred.ts`) OR the legacy plaintext form
+   * `{user, password}` (deprecated — retained for a single
+   * deprecation-cycle window). The two shapes can be mixed in the same
+   * array; the shared `OperCredSchema` validates either.
    */
-  readonly operCreds?: Array<{ user: string; password: string }>;
+  readonly operCreds?: ReadonlyArray<OperCred>;
 }
 
 export interface StartServerOptions extends LocalServerConfig {
@@ -385,13 +395,15 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
   // matches wall time.
   const history = new InMemoryNickHistoryStore({ now: () => Date.now() });
 
-  // SASL account store: seeded from config so `AUTHENTICATE PLAIN` works
-  // end-to-end. `undefined` (no accounts configured) leaves the actor's
-  // `ctx.accounts` unset, preserving the no-store behaviour.
-  const accounts =
-    cfg.saslAccounts !== undefined && cfg.saslAccounts.length > 0
-      ? new InMemoryAccountStore(cfg.saslAccounts)
-      : undefined;
+  // Services store: the single credential home for NickServ, SASL PLAIN,
+  // SASL EXTERNAL, and PASS-auth. Seeded from `saslAccounts` config so the
+  // listed accounts verify end-to-end via `services.verifyNick`. Always
+  // bound (never `undefined`) so NickServ REGISTER / IDENTIFY work
+  // out-of-the-box for local development.
+  const services = new InMemoryServicesStore({ clock: SystemClock });
+  for (const acct of cfg.saslAccounts ?? []) {
+    services.registerNick(acct.username, acct.password, '');
+  }
 
   const wss = new WebSocketServer({
     port: opts.port,
@@ -434,7 +446,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     wsModes.set(ws, subproto);
     const frameMode = wsFrameModeFor(subproto ?? undefined);
 
-    const { state, actor } = attachConnection(runtime, cfg, messages, accounts, history, {
+    const { state, actor } = attachConnection(runtime, cfg, messages, services, history, {
       sendText: (text) => {
         if (ws.readyState !== WebSocket.OPEN) return;
         // binary.ircv3.net connections exchange binary WebSocket frames;
@@ -521,7 +533,16 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       const tcpSockets = new Set<Socket>();
       const tcpServer = createServer((socket) => {
         tcpSockets.add(socket);
-        const scanner = new LineScanner();
+        const scanner = new LineScanner({
+          // A > 8 KiB unterminated tail is pure attacker-controlled memory
+          // (no legal IRC line can exceed 512 bytes): answer with the
+          // RFC-style ERROR notice and destroy the socket. Cleanup runs in
+          // the shared 'close' handler below.
+          onOverflow: () => {
+            safeSocketWrite(socket, 'ERROR :Closing link: input buffer overflow\r\n');
+            socket.destroy();
+          },
+        });
 
         // Admission gate — same policy as the WS path: refuse before the
         // actor is attached so per-IP / per-user counters stay authoritative.
@@ -539,7 +560,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
         const admissionRecordId = decision.recordId;
         runtime.commitAdmission(ip, undefined, admissionRecordId);
 
-        const { state, actor } = attachConnection(runtime, cfg, messages, accounts, history, {
+        const { state, actor } = attachConnection(runtime, cfg, messages, services, history, {
           sendText: (text) => {
             safeSocketWrite(socket, text);
           },
@@ -630,7 +651,7 @@ function attachConnection(
   runtime: InMemoryRuntime,
   cfg: ResolvedServerConfig,
   messages: MessageStore,
-  accounts: AccountStore | undefined,
+  services: ServicesStore,
   history: NickHistoryStore,
   transport: {
     sendText: (text: string) => void;
@@ -680,8 +701,12 @@ function attachConnection(
     ids: DEFAULT_ID_FACTORY,
     motd: { lines: () => cfg.motdLines },
     messages,
-    ...(accounts !== undefined ? { accounts } : {}),
+    ...(services !== undefined ? { services } : {}),
     history,
+    // Shared per-IP failed-OPER counter: one budget per source host across
+    // every connection the CLI hosts (runtime-owned, bound to the runtime
+    // clock). Drives the OPER brute-force lockout.
+    operFailures: runtime.operFailures,
     logger,
     ...(transport.actorTransport !== undefined ? { transport: transport.actorTransport } : {}),
   });

package/apps/local-cli/tests/line-scanner.test.ts

@@ -79,3 +79,67 @@ describe('LineScanner', () => {
     expect(sc.flush()).toEqual([]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Input buffer cap: a peer streaming megabytes with no line terminator must
+// not grow the carry unboundedly. The cap is 8 KiB of raw bytes on the
+// retained (unterminated) tail, checked once per push — complete lines
+// flushed by the same chunk never count against the budget.
+// ---------------------------------------------------------------------------
+
+describe('LineScanner — input buffer cap', () => {
+  it('signals onOverflow and drops the carry when an appended tail exceeds the 8 KiB cap', () => {
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    expect(sc.push(enc('x'.repeat(9 * 1024)))).toEqual([]);
+    expect(overflows.length).toBe(1);
+    // The oversized tail is dropped, not retained.
+    expect(sc.flush()).toEqual([]);
+  });
+
+  it('checks the cap once per push (chunk), not per byte', () => {
+    // A single 9 KiB chunk that overflows fires the callback exactly once —
+    // the guard runs on the appended carry, not per input byte.
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    sc.push(enc('y'.repeat(9 * 1024)));
+    expect(overflows.length).toBe(1);
+  });
+
+  it('signals overflow only on the push that crosses the cap (accumulated chunks)', () => {
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    expect(sc.push(enc('a'.repeat(4 * 1024)))).toEqual([]);
+    expect(overflows.length).toBe(0);
+    expect(sc.push(enc('b'.repeat(5 * 1024)))).toEqual([]);
+    expect(overflows.length).toBe(1);
+  });
+
+  it('does NOT overflow a buffered partial line at (just under) the cap', () => {
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    // Exactly 8192 bytes: at the cap, still allowed.
+    sc.push(enc('z'.repeat(8192)));
+    expect(overflows.length).toBe(0);
+    expect(sc.flush()).toEqual(['z'.repeat(8192)]);
+  });
+
+  it('does not overflow a chunk of complete lines totalling over the cap (batching)', () => {
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    // 20 terminated ~500-byte lines ≈ 10 KiB in one chunk: every line is
+    // complete, so the carry is empty and nothing overflows.
+    const chunk = `${Array.from({ length: 20 }, (_, i) => `PING :${`${i}`.padStart(495, '-')}`).join('\r\n')}\r\n`;
+    expect(chunk.length).toBeGreaterThan(8192);
+    expect(sc.push(enc(chunk)).length).toBe(20);
+    expect(overflows.length).toBe(0);
+  });
+
+  it('measures the carry in bytes (multi-byte UTF-8 counts at wire size)', () => {
+    // 'é' encodes to 2 UTF-8 bytes: 5000 × é = 10000 bytes > 8192.
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    sc.push(enc('é'.repeat(5000)));
+    expect(overflows.length).toBe(1);
+  });
+});

package/apps/local-cli/tests/tcp.test.ts

@@ -275,6 +275,35 @@ describe('local-cli TCP transport — IRC flows', () => {
     await client.close();
   });
 
+  it('closes the TCP connection with ERROR when the input buffer cap is exceeded', async () => {
+    // A peer streaming > 8 KiB with no line terminator would grow the
+    // LineScanner carry unboundedly; the server must answer with the
+    // RFC-style ERROR notice, destroy the socket, and unregister the
+    // connection from the runtime.
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK overflower');
+    await client.send('USER overflower 0 * :Over');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    const connId = await server.runtime.lookupNick('overflower');
+    expect(connId).not.toBeNull();
+    expect(server.runtime.hasConnection(connId as string)).toBe(true);
+
+    const closed = new Promise<void>((resolve) => client.socket.once('close', () => resolve()));
+    await client.writeRaw('x'.repeat(9 * 1024)); // no terminator anywhere
+    const errorLine = await client.waitFor(
+      (l) => l === 'ERROR :Closing link: input buffer overflow',
+      2_000,
+    );
+    expect(errorLine).toBe('ERROR :Closing link: input buffer overflow');
+    await closed;
+    expect(client.socket.destroyed).toBe(true);
+    // Cleanup ran: the runtime no longer tracks the connection.
+    await new Promise((r) => setTimeout(r, 100));
+    expect(server.runtime.hasConnection(connId as string)).toBe(false);
+  });
+
   it('logs an actor failure on the TCP path without crashing the server', async () => {
     const original = server.runtime.send.bind(server.runtime);
     server.runtime.send = async () => {

package/apps/web/landing/index.html

@@ -11,6 +11,7 @@
 <html lang="en">
   <head>
     <meta charset="utf-8" />
+    <link rel="icon" href="/favicon.ico" sizes="any" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>ServerlessIRCd — Serverless IRC Daemon</title>
     <meta

package/apps/web/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@serverless-ircd/web",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "private": true,
   "description": "Web client workspace: Kiwi IRC SPA served at /webclient/ and project landing page at /",
   "license": "BSD-3-Clause",
   "type": "module",
   "scripts": {
     "build": "node scripts/build.mjs",
-    "build:staging": "node scripts/build.mjs --env staging",
     "build:prod": "node scripts/build.mjs --env prod",
+    "build:prod-aws": "node scripts/build.mjs --env prod-aws",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",

package/apps/web/scripts/build.mjs

@@ -3,7 +3,12 @@ import { existsSync } from 'node:fs';
 import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveConfigFile } from '../src/build-env.ts';
+import {
+  hasUnsubstitutedPlaceholder,
+  parseApiUrlForKiwi,
+  resolveApiUrl,
+  resolveConfigFile,
+} from '../src/build-env.ts';
 import { parseKiwiConfig } from '../src/config-schema.ts';
 import { buildDocs } from '../src/render-docs.ts';
 
@@ -107,11 +112,12 @@ await writeFile(indexDest, indexHtml);
 //    so missing fields, out-of-range ports, and non-`#` channels abort the
 //    build here with a readable error. The validated JSON is re-serialised
 //    (stable key order) so the baked config is identical to the schema output.
-const { file: configFileName, env: configEnv } = resolveConfigFile(process.argv.slice(2));
+const argv = process.argv.slice(2);
+const { file: configFileName, env: configEnv } = resolveConfigFile(argv);
 const configSrcPath = path.join(staticDir, configFileName);
 if (!existsSync(configSrcPath)) {
   throw new Error(
-    `Config file for env "${configEnv}" not found at ${configSrcPath}. Expected one of: config.json, config.staging.json, config.prod.json.`,
+    `Config file for env "${configEnv}" not found at ${configSrcPath}. Expected one of: config.json, config.prod.json, config.prod-aws.json.`,
   );
 }
 const configRaw = await readFile(configSrcPath, 'utf8');
@@ -123,6 +129,50 @@ try {
   // offending env config, not just the schema path.
   throw new Error(`${configFileName}: ${err.message}`, { cause: err });
 }
+
+// 4b. AWS deploy pipeline override: `--api-url <wss-url>` (read from the
+//     deployed stack's `ConnectUrl` CloudFormation output by
+//     `scripts/deploy-web-aws.mjs`) replaces the templated `server` value
+//     baked into `config.prod-aws.json` with the real API Gateway
+//     WebSocket host. No concrete URLs in the repo; substitution happens
+//     at deploy time.
+//
+//     irc-framework builds the WS URL as `wss://<server>:<port><direct_path>`,
+//     prepending `wss://` itself whenever `tls: true`. The override MUST
+//     split the URL into a hostname-only `server` and a stage-name
+//     `direct_path` (e.g. `/prod`) — assigning the full `wss://...` URL to
+//     `server` would make irc-framework prepend a second `wss://`,
+//     producing the malformed `wss://wss//<host>...` URL that Firefox
+//     rejects. When the flag is absent (Cloudflare deploys, local dev)
+//     the config's `server`/`direct_path` fields are left untouched.
+const apiUrlOverride = resolveApiUrl(argv);
+if (apiUrlOverride !== undefined) {
+  const { server, directPath } = parseApiUrlForKiwi(apiUrlOverride);
+  configParsed.startupOptions.server = server;
+  if (directPath !== undefined) {
+    configParsed.startupOptions.direct_path = directPath;
+  }
+}
+
+// 4c. Reject unsubstituted AWS deploy-time placeholders — but ONLY when
+//     the selected config is the prod-aws env. The prod-aws config carries
+//     `{{API_ID}}`/`{{REGION}}`/`{{STAGE}}` that MUST be substituted by the
+//     deploy pipeline via `--api-url`; a baked prod-aws build that left
+//     them in place would ship a broken SPA dialling a literal `{{API_ID}}...`
+//     URL.
+//
+//     The CF envs (`default`, `prod`) use Kiwi's runtime templates
+//     (`{{hostname}}`, `{{port}}`) which are resolved in the browser at
+//     load time and must survive the bake. Applying the guard to them
+//     would break every default `pnpm build` and every `build:prod`, so
+//     the helper scopes the check to non-CF envs. See
+//     `hasUnsubstitutedPlaceholder` in `src/build-env.ts`.
+if (hasUnsubstitutedPlaceholder(JSON.stringify(configParsed), configEnv)) {
+  throw new Error(
+    `Refusing to bake ${configFileName} with unsubstituted {{...}} placeholders. Pass --api-url <wss-url> (the deployed stack's ConnectUrl output) to substitute the API Gateway WebSocket URL.`,
+  );
+}
+
 await writeFile(
   path.join(appDist, 'static', 'config.json'),
   `${JSON.stringify(configParsed, null, 2)}\n`,
@@ -133,6 +183,11 @@ await writeFile(
 //    dist/index.html so the Worker `[assets]` binding serves it at `/`. Pure
 //    static HTML + inline CSS (no JS); links to /webclient/ (the SPA),
 //    /docs/ (the rendered docs built in step 6), and the source repo.
+//    Also copies landing/favicon.ico → dist/favicon.ico so both platforms
+//    (CF [assets] binding and AWS `s3 sync apps/web/dist`) serve the
+//    project-front-door icon at /favicon.ico. The Kiwi SPA has its own
+//    icon at /webclient/static/favicon.png (a Kiwi-upstream asset, copied
+//    in step 3); this one is for the landing page only.
 await mkdir(dist, { recursive: true });
 const landingSrc = path.join(pkgRoot, 'landing', 'index.html');
 if (!existsSync(landingSrc)) {
@@ -141,6 +196,13 @@ if (!existsSync(landingSrc)) {
   );
 }
 await cp(landingSrc, path.join(dist, 'index.html'));
+const faviconSrc = path.join(pkgRoot, 'landing', 'favicon.ico');
+if (!existsSync(faviconSrc)) {
+  throw new Error(
+    `Landing page favicon missing at ${faviconSrc}. Expected apps/web/landing/favicon.ico.`,
+  );
+}
+await cp(faviconSrc, path.join(dist, 'favicon.ico'));
 
 // 6. Docs: render every docs/*.md to standalone HTML under dist/docs/ so the
 //    Worker `[assets]` binding serves them at /docs/<name>.html (and /docs/
@@ -150,6 +212,6 @@ await cp(landingSrc, path.join(dist, 'index.html'));
 const docsResult = await buildDocs({ srcDir: docsSrc, outDir: docsDist });
 
 console.log(
-  `Kiwi SPA built -> dist/webclient/ (publicPath=${PUBLIC_PATH}, config=${configFileName}, env=${configEnv})`,
+  `Kiwi SPA built -> dist/webclient/ (publicPath=${PUBLIC_PATH}, config=${configFileName}, env=${configEnv}, apiUrl=${apiUrlOverride === undefined ? 'from-config' : 'overridden'})`,
 );
 console.log(`Docs rendered -> dist/docs/ (${docsResult.emitted.length} pages, index=index.html)`);

package/apps/web/src/build-env.ts

@@ -5,22 +5,36 @@
  * unit-testable without running the (slow) Kiwi upstream build. The build
  * script delegates here and then validates the selected file against
  * {@link parseKiwiConfig} before baking it into `dist/webclient/static/config.json`.
+ *
+ * There is a single Cloudflare deploy target (`prod`); the staging/prod
+ * split was collapsed. `--env prod` selects `config.prod.json`; omitting
+ * `--env` bakes the dev default (`config.json`). `--env staging` is rejected.
+ *
+ * AWS has its own per-env config because the WebSocket endpoint is a separate
+ * API Gateway URL (`wss://{api-id}.execute-api.{region}.amazonaws.com/{stage}`),
+ * not the CloudFront origin serving the SPA. `--env prod-aws` selects
+ * `config.prod-aws.json`, whose `server` carries `{{API_ID}}` / `{{REGION}}`
+ * / `{{STAGE}}` placeholders the deploy pipeline substitutes at bake time
+ * (no concrete URLs in the repo). The `prod-aws` env name is retained for
+ * fidelity with the historical staging/prod nomenclature even though the
+ * staging/prod split is gone — `aws` alone would read as a cleaner label but
+ * is left for a separate rename pass.
  */
 
 /** argv values accepted by `--env`; mapped to a `static/config.<env>.json` file. */
 export const ENV_TO_CONFIG_FILE = {
-  staging: 'config.staging.json',
   prod: 'config.prod.json',
+  'prod-aws': 'config.prod-aws.json',
 } as const;
 
 export type BuildEnv = keyof typeof ENV_TO_CONFIG_FILE;
 
-/** Default config file baked when `--env` is not supplied (staging target). */
+/** Default config file baked when `--env` is not supplied (dev default). */
 export const DEFAULT_CONFIG_FILE = 'config.json';
 
 /**
  * Resolves which `static/config.*.json` the build should bake from the
- * `--env <staging|prod>` CLI flag.
+ * `--env prod` CLI flag.
  *
  * @param argv the CLI args after the script name (typically `process.argv.slice(2)`)
  * @returns `{ file, env }` where `file` is the basename under `static/` and
@@ -31,7 +45,7 @@ export function resolveConfigFile(argv: string[]): { file: string; env: string }
   const envIndex = argv.indexOf('--env');
   const env = envIndex !== -1 ? argv[envIndex + 1] : undefined;
   if (env === undefined) {
-    return { file: DEFAULT_CONFIG_FILE, env: 'default (staging)' };
+    return { file: DEFAULT_CONFIG_FILE, env: 'default' };
   }
   const file = ENV_TO_CONFIG_FILE[env as BuildEnv];
   if (file === undefined) {
@@ -41,3 +55,110 @@ export function resolveConfigFile(argv: string[]): { file: string; env: string }
   }
   return { file, env };
 }
+
+/**
+ * Resolves the optional `--api-url <value>` flag carried on the build argv.
+ *
+ * The AWS web deploy pipeline reads the deployed stack's `ConnectUrl`
+ * CloudFormation output (the API Gateway WebSocket URL) and forwards it
+ * to the SPA build via `--api-url`. The build script then overrides
+ * `startupOptions.server` in the parsed Kiwi config with this value before
+ * baking `dist/webclient/static/config.json`, so the baked SPA carries the
+ * real wss URL instead of the `{{API_ID}}`/`{{REGION}}`/`{{STAGE}}`
+ * template that lives in `static/config.prod-aws.json`. No concrete URLs
+ * are committed; the URL is read from stack outputs at deploy time.
+ *
+ * Returns `undefined` when the flag is absent OR when it is the final
+ * token on the argv (no following value). The caller treats both cases
+ * identically: leave the config's `server` field untouched. The Cloudflare
+ * deploys never pass this flag; only the AWS deploy pipeline does.
+ *
+ * @param argv the CLI args after the script name (typically `process.argv.slice(2)`)
+ * @returns the URL string following `--api-url`, or `undefined` when unset.
+ */
+export function resolveApiUrl(argv: string[]): string | undefined {
+  const i = argv.indexOf('--api-url');
+  if (i === -1) {
+    return undefined;
+  }
+  return argv[i + 1];
+}
+
+/**
+ * Splits a `wss://` API Gateway WebSocket URL into the two Kiwi fields it
+ * becomes at bake time: `server` (hostname only) and `direct_path` (the
+ * stage-name path segment).
+ *
+ * irc-framework builds the WebSocket URL as `wss://<server>:<port><direct_path>`,
+ * prepending the `wss://` scheme itself whenever `tls: true`. Setting
+ * `server` to a full `wss://...` URL would make irc-framework prepend a
+ * second `wss://`, producing a malformed URL that Firefox reports as
+ * `wss://wss//<host>...` (the inner `:` becomes a userinfo separator).
+ *
+ * AWS API Gateway WebSocket URLs include the stage name as a path
+ * segment (`wss://<id>.execute-api.<region>.amazonaws.com/<stage>`) —
+ * that segment must reach the browser as `direct_path`, not as part of
+ * `server`. The CF Worker's WS upgrade is at root, so CF configs leave
+ * `direct_path` unset (or `/`) and `server` is just the hostname.
+ *
+ * @param url a `wss://` or `ws://` URL (the stack's `ConnectUrl` output)
+ * @returns `{ server, directPath }` where `server` is the bare hostname
+ *   and `directPath` is the leading-slash path (e.g. `/prod`) or
+ *   `undefined` when the URL's path is `/` or empty.
+ * @throws {Error} when the URL is missing the `ws://`/`wss://` scheme or
+ *   fails `new URL()` parsing.
+ */
+export function parseApiUrlForKiwi(url: string): {
+  server: string;
+  directPath: string | undefined;
+} {
+  if (!/^wss?:\/\//iu.test(url)) {
+    throw new Error(
+      `--api-url must be a wss:// (or ws://) URL; got: ${url}. irc-framework prepends the scheme itself from tls:true, so the bake must split the URL into a hostname-only server + a direct_path.`,
+    );
+  }
+  const parsed = new URL(url);
+  const directPath =
+    parsed.pathname === '' || parsed.pathname === '/' ? undefined : parsed.pathname;
+  return { server: parsed.hostname, directPath };
+}
+
+/**
+ * Pattern matching any `{{key}}` placeholder, used by both the Kiwi
+ * runtime templates (`{{hostname}}`, `{{host}}`, `{{port}}`) and the
+ * AWS deploy-time placeholders (`{{API_ID}}`, `{{REGION}}`,
+ * `{{STAGE}}`).
+ */
+export const PLACEHOLDER_PATTERN = /\{\{[^}]+\}\}/u;
+
+/**
+ * The Cloudflare deploy envs whose `server` field legitimately bakes
+ * Kiwi runtime templates. The placeholder guard must NOT fire on these
+ * — `{{hostname}}` is resolved by Kiwi in the browser at load time.
+ */
+const RUNTIME_TEMPLATE_ENVS = new Set<string>(['default', 'prod']);
+
+/**
+ * Returns `true` when a baked Kiwi config carries an unsubstituted
+ * placeholder that would produce a broken SPA. The guard is scoped to
+ * the `prod-aws` env: that is the only config whose `server` carries
+ * AWS deploy-time placeholders (`{{API_ID}}`/`{{REGION}}`/`{{STAGE}}`)
+ * that the deploy pipeline (`scripts/deploy-web-aws.mjs`) must
+ * substitute via `--api-url` before baking.
+ *
+ * The Cloudflare envs (`default`, `prod`) use Kiwi's `{{hostname}}`
+ * runtime template, which is resolved by Kiwi in the browser at load
+ * time and MUST survive the bake. Applying the guard to them would
+ * break every default `pnpm build` and every `build:prod`.
+ *
+ * @param bakedConfigJson the serialised config payload about to be
+ *   written to `dist/webclient/static/config.json`.
+ * @param env the selected build env (the `env` field from
+ *   {@link resolveConfigFile}).
+ */
+export function hasUnsubstitutedPlaceholder(bakedConfigJson: string, env: string): boolean {
+  if (RUNTIME_TEMPLATE_ENVS.has(env)) {
+    return false;
+  }
+  return PLACEHOLDER_PATTERN.test(bakedConfigJson);
+}

package/apps/web/src/config-schema.ts

@@ -83,13 +83,27 @@ export const KiwiStartupOptionsSchema = z
     /**
      * WebSocket path on the server. Kiwi reads `direct_path` (NOT `path`) —
      * upstream `helpers/Misc.js:139` copies `config.direct_path` into the
-     * connection info; a `path` field is silently ignored. The Worker exposes
-     * its WS upgrade at root (`worker.ts` routes the upgrade before any path
-     * dispatch), so any path other than `/` would miss the handler. Optional
-     * — when omitted irc-framework builds `wss://host:port` with no path,
-     * which the browser normalises to `wss://host:port/`.
+     * connection info; a `path` field is silently ignored.
+     *
+     * Two valid shapes:
+     *   - CF Worker: WS upgrade is at root, so `direct_path` is `/`.
+     *   - AWS API Gateway: the WebSocket endpoint URL includes the stage
+     *     name as a path segment
+     *     (`wss://<id>.execute-api.<region>.amazonaws.com/<stage>`), so
+     *     `direct_path` MUST be `/<stage>` (e.g. `/prod`). irc-framework
+     *     builds the WS URL as `wss://<server>:<port><direct_path>`.
+     *
+     * The constraint accepts a leading slash plus zero or one path segment
+     * (no nested paths), allowing alphanumeric stage names and the
+     * `{{STAGE}}` placeholder baked into `config.prod-aws.json` for the
+     * deploy pipeline to substitute. Optional — when omitted irc-framework
+     * builds `wss://host:port` with no path, which the browser normalises
+     * to `wss://host:port/` (CF root case).
      */
-    direct_path: z.literal('/').optional(),
+    direct_path: z
+      .string()
+      .regex(/^\/(?:[a-zA-Z0-9._-]+|\{\{[^}]+\}\})?$/u, 'direct_path must be / or /<stage>')
+      .optional(),
   })
   .passthrough();
 

package/apps/web/static/{config.staging.json → config.prod-aws.json}

@@ -1,5 +1,5 @@
 {
-  "windowTitle": "ServerlessIRCd (staging)",
+  "windowTitle": "ServerlessIRCd",
   "startupScreen": "welcome",
   "restricted": false,
   "theme": "Dark",
@@ -15,7 +15,8 @@
     { "name": "Elite", "url": "static/themes/elite" }
   ],
   "startupOptions": {
-    "server": "{{hostname}}",
+    "server": "{{API_ID}}.execute-api.{{REGION}}.amazonaws.com",
+    "direct_path": "/{{STAGE}}",
     "direct": true,
     "tls": true,
     "port": 443,