serverless-ircd 0.9.0 → 0.10.0

package/apps/cf-worker/wrangler.toml

@@ -3,8 +3,7 @@
 ## Cloudflare Worker production config for ServerlessIRCd.
 ##
 ## Deploy:
-##   pnpm deploy:cf:staging     # wrangler deploy --env staging
-##   pnpm deploy:cf:prod        # wrangler deploy
+##   pnpm deploy:cf        # wrangler deploy
 ##
 ## The `apps/cf-worker` worker is the public edge for the IRC service.
 ## It owns the three Durable Object namespaces from the cf-adapter
@@ -13,10 +12,8 @@
 ## `src/worker.ts` and PLAN §6.1.
 ##
 ## Secrets: NEVER put secrets (API tokens, server passwords, account
-## credentials) in this file. Use `wrangler secret put <NAME>` per
-## environment; they live in the Workers KV secrets store, not the repo.
-## As of v1 the worker does not consume any secret bindings — server
-## password, SASL `AccountStore`, and oper creds are future work.
+## credentials) in this file. Use `wrangler secret put <NAME>`;
+## they live in the Workers KV secrets store, not the repo.
 
 name = "serverless-ircd"
 main = "src/worker.ts"
@@ -104,55 +101,20 @@ not_found_handling = "none"
 run_worker_first = true
 
 ## ---------------------------------------------------------------------------
-## Staging environment.
+## D1 database — unified services persistence (NickServ / ChanServ / SASL).
 ## ---------------------------------------------------------------------------
-## `wrangler deploy --env staging` ships to the staging Worker + DO
-## namespace. The CI workflow (`.github/workflows/deploy-cf.yml`) deploys
-## here on every push to `main` and then runs the smoke e2e.
-[env.staging]
-name = "serverless-ircd-staging"
-
-[env.staging.observability]
-enabled = true
-head_sampling_rate = 1
-
-[env.staging.vars]
-SERVER_NAME = "irc-staging.example.com"
-NETWORK_NAME = "ServerlessIRCd (staging)"
-MOTD_LINES = """
-Welcome to ServerlessIRCd staging.
-This is a deployed Cloudflare Worker.
-This Worker was deployed by CI from the main branch.
-"""
-
-# Staging serves the same `apps/web/dist` asset layer. Wrangler requires the
-# per-env assets block so `--env staging` deploys both the Worker and its
-# assets in a single `wrangler deploy --env staging` (the same `pnpm build`
-# populates `dist/` ahead of the deploy step).
-[env.staging.assets]
-directory = "../../apps/web/dist"
-binding = "ASSETS"
-not_found_handling = "none"
-run_worker_first = true
-
-## ---------------------------------------------------------------------------
-## D1 database — SASL account persistence.
-## ---------------------------------------------------------------------------
-## The `accounts` table stores scrypt-hashed SASL PLAIN credentials (never
-## plaintext). Loaded at ConnectionDO construction; when empty or unreachable
-## the resolver falls back to the `SASL_ACCOUNTS` env-var seed. Provision with:
+## The `nickserv_accounts` table is the single credential home for SASL
+## PLAIN, SASL EXTERNAL, PASS-auth, and NickServ IDENTIFY. All scrypt-hashed
+## credentials live here; the standalone `accounts` table was dropped.
+## Provision with:
 ##   wrangler d1 create serverless-ircd-accounts
-##   wrangler d1 execute serverless-ircd-accounts --command \
-##     "CREATE TABLE IF NOT EXISTS accounts (account TEXT PRIMARY KEY, algorithm TEXT NOT NULL, salt TEXT NOT NULL, hash TEXT NOT NULL)"
-## Seed accounts via `tools/seed-cf-accounts.ts`.
+## The services tables self-provision on first load (ConnectionDO runs
+## `CREATE TABLE IF NOT EXISTS` for each table). Seed accounts via
+## `tools/seed-cf-accounts.ts`.
 [[d1_databases]]
 binding = "ACCOUNTS_DB"
 database_name = "serverless-ircd-accounts"
-# database_id is filled in by `wrangler d1 create` and is env-specific.
-
-[[env.staging.d1_databases]]
-binding = "ACCOUNTS_DB"
-database_name = "serverless-ircd-accounts-staging"
+# database_id is filled in by `wrangler d1 create`.
 
 ## ---------------------------------------------------------------------------
 ## Durable Object bindings.
@@ -179,23 +141,6 @@ class_name = "ChannelDO"
 name = "CHANNEL_REGISTRY_DO"
 class_name = "ChannelRegistryDO"
 
-# Staging environment bindings (wrangler requires per-env blocks).
-[[env.staging.durable_objects.bindings]]
-name = "CONNECTION_DO"
-class_name = "ConnectionDO"
-
-[[env.staging.durable_objects.bindings]]
-name = "REGISTRY_DO"
-class_name = "RegistryDO"
-
-[[env.staging.durable_objects.bindings]]
-name = "CHANNEL_DO"
-class_name = "ChannelDO"
-
-[[env.staging.durable_objects.bindings]]
-name = "CHANNEL_REGISTRY_DO"
-class_name = "ChannelRegistryDO"
-
 # ## ---------------------------------------------------------------------------
 # ## Durable Object migrations.
 # ## ---------------------------------------------------------------------------
@@ -210,10 +155,6 @@ class_name = "ChannelRegistryDO"
 # tag = "v1"
 # new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO"]
 
-# [[env.staging.migrations]]
-# tag = "v1"
-# new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO"]
-
 [exports.ConnectionDO]
 type = "durable-object"
 storage = "sqlite"

package/apps/local-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/local-cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": true,
   "description": "Runnable WebSocket IRC server using the in-memory runtime; manual-test harness and e2e fixture target",
   "license": "BSD-3-Clause",

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

@@ -33,20 +33,21 @@ 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 RawLine,
   type ServerConfig,
+  type ServicesStore,
+  SystemClock,
   WS_SUBPROTO_BINARY,
   WS_SUBPROTO_TEXT,
   type WsFrameMode,
@@ -168,10 +169,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 }>;
   /**
@@ -385,13 +387,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 +438,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;
@@ -539,7 +543,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 +634,7 @@ function attachConnection(
   runtime: InMemoryRuntime,
   cfg: ResolvedServerConfig,
   messages: MessageStore,
-  accounts: AccountStore | undefined,
+  services: ServicesStore,
   history: NickHistoryStore,
   transport: {
     sendText: (text: string) => void;
@@ -680,7 +684,7 @@ function attachConnection(
     ids: DEFAULT_ID_FACTORY,
     motd: { lines: () => cfg.motdLines },
     messages,
-    ...(accounts !== undefined ? { accounts } : {}),
+    ...(services !== undefined ? { services } : {}),
     history,
     logger,
     ...(transport.actorTransport !== undefined ? { transport: transport.actorTransport } : {}),

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.10.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,