serverless-ircd 0.10.0 → 0.11.0

package/packages/irc-server/tests/dispatch.test.ts

@@ -21,6 +21,9 @@ function fakeRuntime(calls: RecordedCall[]): IrcRuntime {
     async broadcastWallops(lines, except) {
       calls.push({ method: 'broadcastWallops', args: [lines, except] });
     },
+    async broadcastOperNotice(lines, except) {
+      calls.push({ method: 'broadcastOperNotice', args: [lines, except] });
+    },
     async disconnect(conn, reason) {
       calls.push({ method: 'disconnect', args: [conn, reason] });
     },
@@ -151,6 +154,30 @@ describe('dispatch', () => {
     });
   });
 
+  it('routes BroadcastOperNotice with lines and except', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [Effect.broadcastOperNotice([L(':s NOTICE * :OPER lockout triggered for h')], 'c1')],
+      fakeRuntime(calls),
+    );
+    expect(calls[0]).toEqual({
+      method: 'broadcastOperNotice',
+      args: [[{ text: ':s NOTICE * :OPER lockout triggered for h' }], 'c1'],
+    });
+  });
+
+  it('routes BroadcastOperNotice preserving undefined except', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [Effect.broadcastOperNotice([L(':s NOTICE * :OPER lockout triggered for h')])],
+      fakeRuntime(calls),
+    );
+    expect(calls[0]).toEqual({
+      method: 'broadcastOperNotice',
+      args: [[{ text: ':s NOTICE * :OPER lockout triggered for h' }], undefined],
+    });
+  });
+
   it('calls reserveNick, changeNick, releaseNick in order', async () => {
     const calls: RecordedCall[] = [];
     await dispatch(
@@ -279,6 +306,7 @@ function capAwareRuntime(members: ReadonlyMap<ConnId, MemberInfo>): {
       broadcasts.push({ chan, lines, except });
     },
     async broadcastWallops() {},
+    async broadcastOperNotice() {},
     async disconnect() {},
     async sendToNick() {},
     async reserveNick() {
@@ -429,6 +457,7 @@ describe('dispatch — Broadcast cap / capLines', () => {
       },
       async broadcast() {},
       async broadcastWallops() {},
+      async broadcastOperNotice() {},
       async disconnect() {},
       async sendToNick() {},
       async reserveNick() {
@@ -476,6 +505,7 @@ describe('dispatch — Broadcast cap / capLines', () => {
       },
       async broadcast() {},
       async broadcastWallops() {},
+      async broadcastOperNotice() {},
       async disconnect() {},
       async sendToNick() {},
       async reserveNick() {
@@ -662,6 +692,7 @@ describe('dispatch — Broadcast caps (OR semantics)', () => {
       },
       async broadcast() {},
       async broadcastWallops() {},
+      async broadcastOperNotice() {},
       async disconnect() {},
       async sendToNick() {},
       async reserveNick() {

package/packages/irc-server/tests/redact.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Log-scrubbing helpers: `redactLine`, `truncateToken`, `parseErrorReason`.
+ *
+ * These are the credential-exfiltration guards for log payloads. A hostile
+ * client can smuggle secret material into server logs by sending a
+ * malformed or sensitive line (e.g. `PASS hunter2` inside a frame that
+ * trips the parser). Anything that could end up in a warn/error record
+ * must pass through these helpers first: raw lines go through
+ * `redactLine`, parse diagnostics go through `truncateToken` +
+ * `parseErrorReason`.
+ *
+ * Coverage here is exhaustive by design (100% on this module is a
+ * release requirement): every sensitive command prefix and every branch
+ * of the scrubbers is pinned by a named case.
+ */
+
+import { MAX_TAGS, parse, parseTags } from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import { parseErrorReason, redactLine, truncateToken } from '../src/redact';
+
+describe('redactLine — sensitive command prefixes', () => {
+  it('redacts the parameter of PASS while keeping the verb', () => {
+    expect(redactLine('PASS hunter2')).toBe('PASS [REDACTED]');
+  });
+
+  it('matches the PASS verb case-insensitively but preserves its spelling', () => {
+    expect(redactLine('pass hunter2')).toBe('pass [REDACTED]');
+  });
+
+  it('redacts the parameter of AUTHENTICATE (SASL payloads carry credentials)', () => {
+    expect(redactLine('AUTHENTICATE dXNlcjpodW50ZXIy')).toBe('AUTHENTICATE [REDACTED]');
+  });
+
+  it('redacts the parameters of OPER (name + password)', () => {
+    expect(redactLine('OPER admin secretpw')).toBe('OPER [REDACTED]');
+  });
+
+  it('redacts the parameter of a bare IDENTIFY (service shortcut form)', () => {
+    expect(redactLine('IDENTIFY hunter2')).toBe('IDENTIFY [REDACTED]');
+  });
+
+  it('redacts a NickServ-targeted PRIVMSG carrying IDENTIFY, keeping target + subcommand', () => {
+    expect(redactLine('PRIVMSG NickServ :IDENTIFY hunter2')).toBe(
+      'PRIVMSG NickServ :IDENTIFY [REDACTED]',
+    );
+  });
+
+  it('redacts a case-folded NickServ-targeted NOTICE carrying the ID alias', () => {
+    expect(redactLine('NOTICE nickserv :id hunter2')).toBe('NOTICE nickserv :id [REDACTED]');
+  });
+
+  it('redacts a NickServ-targeted PRIVMSG whose body lacks the trailing colon', () => {
+    expect(redactLine('PRIVMSG NickServ IDENTIFY hunter2')).toBe(
+      'PRIVMSG NickServ IDENTIFY [REDACTED]',
+    );
+  });
+});
+
+describe('redactLine — non-sensitive input passes through', () => {
+  it('leaves ordinary commands untouched', () => {
+    expect(redactLine('PRIVMSG #chan :hello there')).toBe('PRIVMSG #chan :hello there');
+  });
+
+  it('leaves a NickServ message that carries no credential subcommand untouched', () => {
+    expect(redactLine('PRIVMSG NickServ :INFO')).toBe('PRIVMSG NickServ :INFO');
+  });
+
+  it('leaves an IDENTIFY with no arguments untouched (nothing to redact)', () => {
+    expect(redactLine('PRIVMSG NickServ :IDENTIFY')).toBe('PRIVMSG NickServ :IDENTIFY');
+  });
+
+  it('leaves an IDENTIFY sent to a non-service nick untouched', () => {
+    expect(redactLine('PRIVMSG Mallory :IDENTIFY hunter2')).toBe(
+      'PRIVMSG Mallory :IDENTIFY hunter2',
+    );
+  });
+
+  it('leaves a bare sensitive verb with no parameters untouched', () => {
+    expect(redactLine('PASS')).toBe('PASS');
+  });
+
+  it('leaves a bare PRIVMSG with no target or body untouched', () => {
+    expect(redactLine('PRIVMSG')).toBe('PRIVMSG');
+  });
+
+  it('leaves an empty line untouched', () => {
+    expect(redactLine('')).toBe('');
+  });
+});
+
+describe('redactLine — source prefixes', () => {
+  it('redacts the parameters of a prefixed sensitive command, keeping the prefix', () => {
+    expect(redactLine(':srv.example.com PASS secret')).toBe(':srv.example.com PASS [REDACTED]');
+  });
+
+  it('redacts a prefixed NickServ-targeted PRIVMSG', () => {
+    expect(redactLine(':alice!u@h PRIVMSG NickServ :IDENTIFY hunter2')).toBe(
+      ':alice!u@h PRIVMSG NickServ :IDENTIFY [REDACTED]',
+    );
+  });
+
+  it('leaves a prefix-only line untouched', () => {
+    expect(redactLine(':prefix-only')).toBe(':prefix-only');
+  });
+});
+
+describe('truncateToken', () => {
+  it('returns a token at the cap unchanged', () => {
+    expect(truncateToken('a'.repeat(32))).toBe('a'.repeat(32));
+  });
+
+  it('truncates a token beyond the cap with an ellipsis marker', () => {
+    expect(truncateToken('a'.repeat(33))).toBe(`${'a'.repeat(32)}...`);
+  });
+});
+
+describe('parseErrorReason — stable codes for every parser diagnostic', () => {
+  it('maps the empty-message diagnostic', () => {
+    expect(() => parse('')).toThrow();
+    try {
+      parse('');
+    } catch (err) {
+      expect(parseErrorReason(err)).toBe('empty-message');
+    }
+  });
+
+  it('maps the input-cap diagnostic', () => {
+    try {
+      parse('A'.repeat(600));
+      expect.unreachable('600 bytes must fail the input cap');
+    } catch (err) {
+      expect(parseErrorReason(err)).toBe('input-cap-exceeded');
+    }
+  });
+
+  it('maps the tags-without-body diagnostic', () => {
+    try {
+      parse('@account=alice');
+      expect.unreachable('a tag section with no message body must fail');
+    } catch (err) {
+      expect(parseErrorReason(err)).toBe('tags-without-body');
+    }
+  });
+
+  it('maps the prefix-without-command diagnostic', () => {
+    try {
+      parse(':src.example.com');
+      expect.unreachable('a source prefix with no command must fail');
+    } catch (err) {
+      expect(parseErrorReason(err)).toBe('prefix-without-command');
+    }
+  });
+
+  it('maps the missing-command diagnostic', () => {
+    try {
+      parse('@a :src ');
+      expect.unreachable('tags + prefix with no command must fail');
+    } catch (err) {
+      expect(parseErrorReason(err)).toBe('missing-command');
+    }
+  });
+
+  it('maps the invalid-command-token diagnostic', () => {
+    try {
+      parse('12345');
+      expect.unreachable('a 5-digit command token must fail');
+    } catch (err) {
+      expect(parseErrorReason(err)).toBe('invalid-command-token');
+    }
+  });
+
+  it('maps the too-many-tags diagnostic', () => {
+    try {
+      const tags = Array.from({ length: MAX_TAGS + 1 }, (_, i) => `t${i}`);
+      parse(`@${tags.join(';')} PRIVMSG #foo :hi`);
+      expect.unreachable('a 16-tag line must fail the tag count cap');
+    } catch (err) {
+      expect(parseErrorReason(err)).toBe('too-many-tags');
+    }
+  });
+
+  it('maps the tag-section-byte-cap diagnostic', () => {
+    try {
+      parseTags(`a=${'x'.repeat(8193 - 2)}`, `@a=${'x'.repeat(8193 - 2)} PRIVMSG #foo :hi`);
+      expect.unreachable('an over-budget tag section must fail');
+    } catch (err) {
+      expect(parseErrorReason(err)).toBe('tag-section-too-large');
+    }
+  });
+
+  it('falls back to a stable code for an unrecognized Error message', () => {
+    expect(parseErrorReason(new Error('boom'))).toBe('parse-failed');
+  });
+
+  it('falls back to a stable code for a non-Error throw', () => {
+    expect(parseErrorReason('boom')).toBe('parse-failed');
+  });
+});

package/packages/irc-server/tests/runtime.test.ts

@@ -38,6 +38,7 @@ describe('IrcRuntime contract', () => {
         throw new Error('reloadConfig not configured for this fake');
       },
       async broadcastWallops() {},
+      async broadcastOperNotice() {},
     };
     expect(runtime).toBeDefined();
     expect(typeof runtime.send).toBe('function');
@@ -55,5 +56,6 @@ describe('IrcRuntime contract', () => {
     expect(typeof runtime.listChannels).toBe('function');
     expect(typeof runtime.reloadConfig).toBe('function');
     expect(typeof runtime.broadcastWallops).toBe('function');
+    expect(typeof runtime.broadcastOperNotice).toBe('function');
   });
 });

package/packages/irc-server/tests/transport.test.ts

@@ -199,6 +199,72 @@ describe('TcpByteStreamTransport — buffer save/restore', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Input buffer cap: a peer streaming megabytes with no line terminator must
+// not grow the partial-line buffer unboundedly (edge-level memory DoS). The
+// cap is measured in UTF-8 bytes on the retained (unterminated) tail after
+// each append — complete lines flushed out by the same chunk never count.
+// ---------------------------------------------------------------------------
+
+describe('TcpByteStreamTransport — input buffer cap', () => {
+  it('signals onOverflow and drops the buffer when an appended tail exceeds the 8 KiB cap', () => {
+    const overflows: number[] = [];
+    const t = new TcpByteStreamTransport({ onOverflow: () => overflows.push(1) });
+    expect(t.feed('x'.repeat(9 * 1024))).toEqual([]);
+    expect(overflows.length).toBe(1);
+    // The oversized tail is dropped, not retained.
+    expect(t.getBuffer()).toBe('');
+  });
+
+  it('checks the cap once per append (chunk), not per byte', () => {
+    // A single 9 KiB chunk that overflows fires the callback exactly once —
+    // the guard runs on the appended buffer, not per input byte.
+    const overflows: number[] = [];
+    const t = new TcpByteStreamTransport({ onOverflow: () => overflows.push(1) });
+    t.feed('y'.repeat(9 * 1024));
+    expect(overflows.length).toBe(1);
+  });
+
+  it('signals overflow only on the append that crosses the cap (accumulated chunks)', () => {
+    const overflows: number[] = [];
+    const t = new TcpByteStreamTransport({ onOverflow: () => overflows.push(1) });
+    expect(t.feed('a'.repeat(4 * 1024))).toEqual([]);
+    expect(overflows.length).toBe(0);
+    expect(t.feed('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 t = new TcpByteStreamTransport({ onOverflow: () => overflows.push(1) });
+    // Exactly 8192 bytes: at the cap, still allowed.
+    t.feed('z'.repeat(8192));
+    expect(overflows.length).toBe(0);
+    expect(t.getBuffer()).toBe('z'.repeat(8192));
+  });
+
+  it('does not overflow a chunk of complete lines totalling over the cap (batching)', () => {
+    const overflows: number[] = [];
+    const t = new TcpByteStreamTransport({ onOverflow: () => overflows.push(1) });
+    // 20 terminated ~500-byte lines ≈ 10 KiB in one chunk: every line is
+    // complete, so the retained tail 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);
+    const out = t.feed(chunk);
+    expect(overflows.length).toBe(0);
+    expect(out.length).toBe(20);
+    expect(t.getBuffer()).toBe('');
+  });
+
+  it('measures the tail in UTF-8 bytes, not UTF-16 code units', () => {
+    // 'é' is one UTF-16 unit but two UTF-8 bytes: 5000 × é = 10000 bytes.
+    const overflows: number[] = [];
+    const t = new TcpByteStreamTransport({ onOverflow: () => overflows.push(1) });
+    t.feed('é'.repeat(5000));
+    expect(overflows.length).toBe(1);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Equivalence: a fully-terminated message stream produces the same complete
 // lines regardless of how it is chunked across feed() calls.

package/packages/irc-test-support/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-test-support",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "description": "Shared IRC scenario runner + harness seam used by every adapter's integration suite",
   "license": "BSD-3-Clause",

package/packages/irc-test-support/src/in-memory-harness.ts

@@ -192,6 +192,10 @@ export class InMemoryHarness implements IrcHarness {
       clock: this.clock,
       ids: this.ids,
       motd: this.motd,
+      // Shared per-IP failed-OPER counter (runtime-owned) so harness
+      // scenarios exercise the OPER brute-force lockout exactly like the
+      // local CLI does.
+      operFailures: this.runtime.operFailures,
       transport: this.newTransport(),
     });
     client.bindActor(actor);

package/scripts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/deploy-scripts",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "description": "Repo-level deploy helpers (AWS web client s3 sync + CloudFront invalidation pipeline).",
   "license": "BSD-3-Clause",

package/tools/ci-hardening/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@serverless-ircd/ci-hardening",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
-  "description": "CI hardening helpers: coverage-gate config validator + mutation-testing driver for irc-core",
+  "description": "CI hardening helpers: coverage-gate config validator + mutation-testing driver for irc-core + deploy hostname placeholder guard",
   "license": "BSD-3-Clause",
   "type": "module",
   "main": "./dist/index.js",

package/tools/ci-hardening/src/cf-deploy-cli.ts

@@ -0,0 +1,3 @@
+import { runDeploy } from './cf-deploy.js';
+
+process.exit(runDeploy(process.argv.slice(2), process.env));

package/tools/ci-hardening/src/cf-deploy.ts

@@ -0,0 +1,118 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { checkDeployHostname, readServerNameFromWranglerToml } from './deploy-hostname.js';
+
+/**
+ * Guarded `wrangler deploy` wrapper for the Cloudflare apps.
+ *
+ * Runs the deploy-time hostname guard and injects the resolved
+ * SERVER_NAME into the wrangler invocation itself, so an operator
+ * setting ONE override (`SERVER_NAME=irc.example.org pnpm deploy:cf`)
+ * satisfies both the guard and the deployed var. Without the wrapper
+ * the guard reads the env var but wrangler ignores it (vars come from
+ * wrangler.toml / --var flags), forcing the value to be specified
+ * twice.
+ *
+ * Usage (from an app's npm script, cwd = the app dir):
+ *
+ *   node ../../tools/ci-hardening/dist/cf-deploy-cli.js wrangler.toml -- <wrangler args...>
+ *
+ * Resolution order: a non-blank `SERVER_NAME` env override wins; else
+ * the `[vars]` SERVER_NAME in the config. The resolved value is always
+ * passed to wrangler as `--var SERVER_NAME:<hostname>` (identical to
+ * the config value in the fallback case, an override otherwise) and
+ * validated by the same placeholder guard as the deploy workflows.
+ */
+
+export interface WrapperArgv {
+  readonly configPath: string;
+  readonly passthrough: readonly string[];
+}
+
+/**
+ * Parses the wrapper argv: first positional is the wrangler.toml path;
+ * everything after it (with leading `--` separators stripped, which
+ * pnpm appends for `pnpm deploy:cf -- <args>`) is passed through to
+ * `wrangler deploy`.
+ */
+export function parseWrapperArgv(argv: readonly string[]): WrapperArgv {
+  const configPath = argv[0] ?? '';
+  const rest = argv.slice(1);
+  // Strip every leading `--` separator — pnpm forwarding can produce
+  // more than one (`pnpm deploy:cf -- --flag` on a script that itself
+  // ends in `--`); wrangler would treat them as positionals.
+  let i = 0;
+  while (i < rest.length && rest[i] === '--') i++;
+  return { configPath, passthrough: rest.slice(i) };
+}
+
+export type GuardedHostname = { ok: true; hostname: string } | { ok: false; message: string };
+
+/**
+ * Resolves the deploy-time hostname (env override → config `[vars]`
+ * SERVER_NAME) and runs it through the placeholder guard.
+ */
+export function resolveGuardedHostname(
+  configPath: string,
+  env: Record<string, string | undefined>,
+): GuardedHostname {
+  const override = env.SERVER_NAME;
+  const hostname =
+    typeof override === 'string' && override.trim() !== ''
+      ? override
+      : readServerNameFromWranglerToml(readFileSync(configPath, 'utf8'));
+  if (hostname === undefined) {
+    return {
+      ok: false,
+      message: `::error::SERVER_NAME is not set: no SERVER_NAME var found in ${configPath} and no SERVER_NAME environment override is set`,
+    };
+  }
+  const check = checkDeployHostname(hostname);
+  return check.ok
+    ? { ok: true, hostname: check.hostname }
+    : { ok: false, message: `::error::${check.error}` };
+}
+
+/**
+ * Builds the wrangler argument vector: `deploy` with the resolved
+ * hostname injected as a `--var` override, followed by any passthrough
+ * flags (`--dry-run`, `--keep-vars`, …). Uses the documented
+ * `KEY:value` pair syntax.
+ */
+export function buildWranglerDeployArgs(
+  hostname: string,
+  passthrough: readonly string[],
+): string[] {
+  return ['deploy', '--var', `SERVER_NAME:${hostname}`, ...passthrough];
+}
+
+const USAGE =
+  'usage: cf-deploy <wrangler.toml> [-- <wrangler deploy args...>] (SERVER_NAME env var optionally overrides the config value)';
+
+/**
+ * Resolves + guards, then execs `wrangler` (resolved from PATH — the
+ * npm script context puts node_modules/.bin there) with the resolved
+ * hostname injected. Returns the process exit code to propagate.
+ */
+export function runDeploy(
+  argv: readonly string[],
+  env: Record<string, string | undefined>,
+): number {
+  const { configPath, passthrough } = parseWrapperArgv(argv);
+  if (configPath === '') {
+    console.error(USAGE);
+    return 2;
+  }
+  const resolved = resolveGuardedHostname(configPath, env);
+  if (!resolved.ok) {
+    console.error(resolved.message);
+    return 1;
+  }
+  const args = buildWranglerDeployArgs(resolved.hostname, passthrough);
+  const result = spawnSync('wrangler', args, { stdio: 'inherit' });
+  if (result.error !== undefined) {
+    console.error(`::error::failed to run wrangler: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}

package/tools/ci-hardening/src/deploy-hostname.ts

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Hostnames the repo ships as defaults in its deploy configs
+ * (`SERVER_NAME = "irc.your-domain.invalid"` in both wrangler.toml
+ * files, `irc.example.com` in the Spectrum apply docs/defaults).
+ *
+ * A deploy whose public hostname is still one of these values is a
+ * misconfiguration, not a deploy: the wss Worker would advertise the
+ * placeholder in its numerics and the Spectrum cert/handshake would
+ * target a domain the operator does not own. Deploy paths refuse to
+ * ship while the deploy-time hostname is on this list.
+ */
+export const PLACEHOLDER_HOSTNAMES: ReadonlySet<string> = new Set([
+  'irc.example.com',
+  'irc.your-domain.invalid',
+]);
+
+/**
+ * Whether a hostname is one of the repo's shipping placeholders.
+ * Hostnames are case-insensitive and tolerant of surrounding
+ * whitespace (workflow inputs / env vars).
+ */
+export function isPlaceholderHostname(hostname: string): boolean {
+  return PLACEHOLDER_HOSTNAMES.has(hostname.trim().toLowerCase());
+}
+
+export type HostnameCheck = { ok: true; hostname: string } | { ok: false; error: string };
+
+/**
+ * Validate a deploy-time hostname. Returns the trimmed, lowercased
+ * hostname on success; on failure returns an `error` explaining how
+ * to set a real one (workflow `hostname` input, or `SERVER_NAME` in
+ * the app's wrangler.toml `[vars]` block).
+ */
+export function checkDeployHostname(raw: string | undefined | null): HostnameCheck {
+  const hostname = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+  if (hostname === '') {
+    return {
+      ok: false,
+      error:
+        'deploy hostname is required: pass the public IRC hostname via the workflow `hostname` input (deploy-cf / deploy-cf-tcp) or set SERVER_NAME in the app wrangler.toml [vars] block',
+    };
+  }
+  if (isPlaceholderHostname(hostname)) {
+    return {
+      ok: false,
+      error: `${hostname} is a placeholder hostname shipped with the repo defaults, not a real deploy target: set the public IRC hostname (workflow \`hostname\` input or SERVER_NAME in wrangler.toml [vars]) and redeploy`,
+    };
+  }
+  return { ok: true, hostname };
+}
+
+const SERVER_NAME_RE = /^\s*SERVER_NAME\s*=\s*["']([^"'\r\n]+)["']\s*$/m;
+
+/**
+ * Extract the `SERVER_NAME` var from wrangler.toml text. Anchored at
+ * line starts so commented-out (`# SERVER_NAME = ...`) assignments
+ * do not match; accepts both TOML quote styles.
+ */
+export function readServerNameFromWranglerToml(tomlText: string): string | undefined {
+  return tomlText.match(SERVER_NAME_RE)?.[1];
+}
+
+export interface HostnameGuardResult {
+  /** 0 = deployable, 1 = rejected (unset or placeholder), 2 = usage error. */
+  exitCode: number;
+  message: string;
+}
+
+const USAGE = 'usage: hostname-guard <hostname> | hostname-guard --from-config <wrangler.toml>';
+
+function report(check: HostnameCheck): HostnameGuardResult {
+  return check.ok
+    ? { exitCode: 0, message: `deploy hostname OK: ${check.hostname}` }
+    : { exitCode: 1, message: `::error::${check.error}` };
+}
+
+/**
+ * The deploy-time hostname guard. Two modes:
+ *
+ * - `hostname-guard <hostname>` — validate an explicit value (the
+ *   deploy workflows pass their `hostname` input through this).
+ * - `hostname-guard --from-config <wrangler.toml>` — validate the
+ *   deploy-time SERVER_NAME: the `SERVER_NAME` env override if set
+ *   and non-blank, else the `[vars]` SERVER_NAME in the config (the
+ *   guarded `wrangler deploy` npm scripts use this).
+ *
+ * Pure with respect to the process: `main` wires `process.argv` /
+ * `process.env` / stdio / `process.exit`.
+ */
+export function runHostnameGuard(
+  argv: readonly string[],
+  env: Record<string, string | undefined>,
+): HostnameGuardResult {
+  if (argv[0] === '--from-config') {
+    const configPath = argv[1];
+    if (configPath === undefined || configPath === '') {
+      return { exitCode: 2, message: USAGE };
+    }
+    const override = env.SERVER_NAME;
+    const hostname =
+      typeof override === 'string' && override.trim() !== ''
+        ? override
+        : readServerNameFromWranglerToml(readFileSync(configPath, 'utf8'));
+    if (hostname === undefined) {
+      return {
+        exitCode: 1,
+        message: `::error::SERVER_NAME is not set: no SERVER_NAME var found in ${configPath} and no SERVER_NAME environment override is set`,
+      };
+    }
+    return report(checkDeployHostname(hostname));
+  }
+  if (argv.length === 1) {
+    return report(checkDeployHostname(argv[0]));
+  }
+  return { exitCode: 2, message: USAGE };
+}