serverless-ircd 0.2.0 → 0.4.0

package/packages/cf-adapter/tests/d1-account-store.test.ts

@@ -0,0 +1,226 @@
+/**
+ * D1-backed SASL account store + precedence resolver.
+ *
+ * Exercises the real D1 round-trip via miniflare: `putAccountCredential`
+ * writes a hashed row, `loadD1AccountStore` reads it back, and
+ * `resolveAccountStore` applies the table-then-config precedence.
+ */
+
+import { env } from 'cloudflare:test';
+import { hashAccountCredential } from '@serverless-ircd/irc-core';
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  buildAccountPutStatement,
+  loadD1AccountStore,
+  putAccountCredential,
+  resolveAccountStore,
+} from '../src/d1-account-store';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      ACCOUNTS_DB: D1Database;
+    }
+  }
+}
+
+const CREATE_TABLE =
+  'CREATE TABLE IF NOT EXISTS accounts (account TEXT PRIMARY KEY, algorithm TEXT NOT NULL, salt TEXT NOT NULL, hash TEXT NOT NULL)';
+
+async function resetDb(): Promise<void> {
+  await env.ACCOUNTS_DB.exec('DROP TABLE IF EXISTS accounts');
+  await env.ACCOUNTS_DB.exec(CREATE_TABLE);
+}
+
+describe('loadD1AccountStore', () => {
+  beforeEach(async () => {
+    await resetDb();
+  });
+
+  it('returns undefined when the table has no rows', async () => {
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store).toBeUndefined();
+  });
+
+  it('verifies an account after a row is written via putAccountCredential', async () => {
+    await putAccountCredential(env.ACCOUNTS_DB, 'alice', 's3cret');
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store).toBeDefined();
+    expect(
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 's3cret' }),
+    ).toEqual({ ok: true, account: 'alice' });
+  });
+
+  it('rejects a wrong password after round-trip', async () => {
+    await putAccountCredential(env.ACCOUNTS_DB, 'alice', 'right');
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store).toBeDefined();
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'wrong' }).ok).toBe(
+      false,
+    );
+  });
+
+  it('loads multiple distinct accounts', async () => {
+    await putAccountCredential(env.ACCOUNTS_DB, 'alice', 'a1');
+    await putAccountCredential(env.ACCOUNTS_DB, 'bob', 'b2');
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store?.size).toBe(2);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'a1' }).ok).toBe(
+      true,
+    );
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'bob', password: 'b2' }).ok).toBe(
+      true,
+    );
+  });
+
+  it('overwrites an existing account on re-seed', async () => {
+    await putAccountCredential(env.ACCOUNTS_DB, 'alice', 'old');
+    await putAccountCredential(env.ACCOUNTS_DB, 'alice', 'new');
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store?.size).toBe(1);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'old' }).ok).toBe(
+      false,
+    );
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'new' }).ok).toBe(
+      true,
+    );
+  });
+
+  it('skips rows missing required columns', async () => {
+    // Use a permissive table (no NOT NULL) to simulate a row with a missing
+    // salt — the production schema's NOT NULL prevents this, but the loader
+    // stays defensive against schema drift / manual edits.
+    await env.ACCOUNTS_DB.exec('DROP TABLE accounts');
+    await env.ACCOUNTS_DB.exec(
+      'CREATE TABLE accounts (account TEXT PRIMARY KEY, algorithm TEXT, salt TEXT, hash TEXT)',
+    );
+    await env.ACCOUNTS_DB.prepare(
+      "INSERT INTO accounts (account, algorithm, hash) VALUES ('bad', 'scrypt', 'bbbb')",
+    ).run();
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store).toBeUndefined();
+  });
+});
+
+describe('putAccountCredential', () => {
+  beforeEach(async () => {
+    await resetDb();
+  });
+
+  it('writes a hashed row that round-trips through the store', async () => {
+    const entry = await putAccountCredential(env.ACCOUNTS_DB, 'carol', 'p@ss');
+    expect(entry.account).toBe('carol');
+    expect(entry.algorithm).toBe('scrypt');
+
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'carol', password: 'p@ss' })).toEqual({
+      ok: true,
+      account: 'carol',
+    });
+  });
+
+  it('never writes the plaintext password to the row', async () => {
+    const entry = await putAccountCredential(env.ACCOUNTS_DB, 'alice', 'hunter2-secret');
+    expect(entry.account).not.toContain('hunter2');
+    expect(entry.salt).not.toContain('hunter2');
+    expect(entry.hash).not.toContain('hunter2');
+  });
+
+  it('matches a manually-hashed entry written via raw D1 insert', async () => {
+    const hashed = hashAccountCredential('dave', 'pw');
+    await env.ACCOUNTS_DB.prepare(
+      'INSERT INTO accounts (account, algorithm, salt, hash) VALUES (?, ?, ?, ?)',
+    )
+      .bind(hashed.account, hashed.algorithm, hashed.salt, hashed.hash)
+      .run();
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'dave', password: 'pw' }).ok).toBe(
+      true,
+    );
+  });
+});
+
+describe('buildAccountPutStatement (seed SQL builder)', () => {
+  it('produces an INSERT OR REPLACE statement with scrypt-hashed values', () => {
+    const { entry, sql } = buildAccountPutStatement('alice', 's3cret');
+    expect(entry.account).toBe('alice');
+    expect(entry.algorithm).toBe('scrypt');
+    expect(sql).toContain('INSERT OR REPLACE INTO accounts');
+    // Plaintext must never appear in the SQL.
+    expect(sql).not.toContain('s3cret');
+  });
+
+  it('the generated SQL round-trips through loadD1AccountStore', async () => {
+    await resetDb();
+    const { sql } = buildAccountPutStatement('carol', 'p@ss');
+    await env.ACCOUNTS_DB.exec(sql);
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'carol', password: 'p@ss' })).toEqual({
+      ok: true,
+      account: 'carol',
+    });
+  });
+
+  it('escapes single quotes in the username to avoid breaking the SQL', async () => {
+    await resetDb();
+    const { sql } = buildAccountPutStatement("o'brien", 'pw');
+    await env.ACCOUNTS_DB.exec(sql);
+    const store = await loadD1AccountStore(env.ACCOUNTS_DB);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: "o'brien", password: 'pw' }).ok).toBe(
+      true,
+    );
+  });
+
+  it('escapes single quotes in the base64 hash output', () => {
+    // The hash is base64 so it won't contain quotes, but the escaper is
+    // still exercised — verify the SQL is well-formed.
+    const { sql } = buildAccountPutStatement('alice', 'secret');
+    // A valid INSERT with four quoted values.
+    expect(sql.match(/'/g)?.length).toBe(8);
+  });
+});
+
+describe('resolveAccountStore precedence', () => {
+  beforeEach(async () => {
+    await resetDb();
+  });
+
+  it('returns the D1 store when the table has rows (table wins)', async () => {
+    await putAccountCredential(env.ACCOUNTS_DB, 'alice', 'table-secret');
+    const store = await resolveAccountStore(env.ACCOUNTS_DB, 'envuser:env-secret');
+    expect(store).toBeDefined();
+    expect(
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'table-secret' }).ok,
+    ).toBe(true);
+    // Config account does NOT verify (table is authoritative).
+    expect(
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
+    ).toBe(false);
+  });
+
+  it('falls back to the SASL_ACCOUNTS seed when the table is empty', async () => {
+    const store = await resolveAccountStore(env.ACCOUNTS_DB, 'envuser:env-secret');
+    expect(store).toBeDefined();
+    expect(
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
+    ).toBe(true);
+  });
+
+  it('returns undefined when the table is empty and no seed is set', async () => {
+    const store = await resolveAccountStore(env.ACCOUNTS_DB, undefined);
+    expect(store).toBeUndefined();
+  });
+
+  it('returns undefined when the table is empty and the seed is blank', async () => {
+    const store = await resolveAccountStore(env.ACCOUNTS_DB, '');
+    expect(store).toBeUndefined();
+  });
+
+  it('falls back to the seed when the D1 binding is undefined', async () => {
+    const store = await resolveAccountStore(undefined, 'envuser:env-secret');
+    expect(store).toBeDefined();
+    expect(
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
+    ).toBe(true);
+  });
+});

package/packages/cf-adapter/tests/raw-modules.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ambient declaration so `?raw` imports (Vite's built-in transform that
+ * inlines a file's text at bundle time) typecheck under the strict
+ * `tsconfig.test.json`. Used by source-level regression guards that
+ * assert dead code stays removed.
+ */
+declare module '*?raw' {
+  const content: string;
+  // eslint-disable-next-line import/no-default-export
+  export default content;
+}

package/packages/cf-adapter/tests/worker/main.ts

@@ -19,12 +19,20 @@
  */
 
 import { ChannelDO } from '../../src/channel-do';
+import { ChannelRegistryDO } from '../../src/channel-registry-do';
 import { ConnectionDO } from '../../src/connection-do';
 import { RegistryDO } from '../../src/registry-do';
 import { RecordingChannelDO } from './stubs/channel-stub';
 import { RecordingRegistryDO } from './stubs/registry-stub';
 
-export { ChannelDO, ConnectionDO, RegistryDO, RecordingRegistryDO, RecordingChannelDO };
+export {
+  ChannelDO,
+  ChannelRegistryDO,
+  ConnectionDO,
+  RegistryDO,
+  RecordingRegistryDO,
+  RecordingChannelDO,
+};
 
 export default {
   async fetch(): Promise<Response> {

package/packages/cf-adapter/tests/worker/stubs/channel-stub.ts

@@ -12,7 +12,7 @@
 import { DurableObject } from 'cloudflare:workers';
 
 export interface RecordedChannelCall {
-  method: 'broadcast' | 'applyChannelDelta' | 'getChannelSnapshot';
+  method: 'broadcast' | 'applyChannelDelta' | 'getChannelSnapshot' | 'listMembers';
   args: unknown[];
 }
 
@@ -20,6 +20,7 @@ interface ChannelRpc {
   broadcast(lines: unknown[], except?: string): Promise<void>;
   applyChannelDelta(delta: unknown): Promise<void>;
   getChannelSnapshot(): Promise<unknown>;
+  listMembers(): Promise<string[]>;
 }
 
 const LOG_KEY = 'channel-call-log';
@@ -47,4 +48,9 @@ export class RecordingChannelDO extends DurableObject implements ChannelRpc {
     await this.append({ method: 'getChannelSnapshot', args: [] });
     return null;
   }
+
+  async listMembers(): Promise<string[]> {
+    await this.append({ method: 'listMembers', args: [] });
+    return [];
+  }
 }

package/packages/cf-adapter/wrangler.test.toml

@@ -9,6 +9,18 @@ compatibility_flags = ["nodejs_compat"]
 # body text in every runtime factory.
 [vars]
 MOTD_LINES = "Welcome to the ServerlessIRCd integration-test harness.\nAll scenarios run parametrized over the IrcRuntime factory matrix."
+# SASL PLAIN accounts seeded into the in-worker AccountStore. Newline-
+# delimited `username:password` pairs; the connection-do parses these into
+# an InMemoryAccountStore so AUTHENTICATE PLAIN works end-to-end in tests.
+SASL_ACCOUNTS = "cf-sasl:s3cret"
+
+# D1 database backing persistent SASL accounts. The D1 account-store suite
+# creates the `accounts` table in a beforeEach and exercises the real
+# load/put/resolve path.
+[[d1_databases]]
+binding = "ACCOUNTS_DB"
+database_name = "cf-adapter-test-accounts"
+database_id = "test-d1-accounts"
 
 # Production bindings: REGISTRY_DO and CHANNEL_DO point at the real DO
 # classes so CfRuntime, ConnectionDO, and the integration suite all
@@ -25,6 +37,11 @@ class_name = "RegistryDO"
 name = "CHANNEL_DO"
 class_name = "ChannelDO"
 
+# Channel registry — single DO tracking all channel names for LIST.
+[[durable_objects.bindings]]
+name = "CHANNEL_REGISTRY_DO"
+class_name = "ChannelRegistryDO"
+
 # Recording stubs (kept under separate names for any test that wants to
 # assert "this exact RPC was emitted" rather than the end-to-end effect).
 [[durable_objects.bindings]]
@@ -47,4 +64,4 @@ class_name = "ChannelDO"
 
 [[migrations]]
 tag = "v1"
-new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "RecordingRegistryDO", "RecordingChannelDO"]
+new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO", "RecordingRegistryDO", "RecordingChannelDO"]

package/packages/in-memory-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/in-memory-runtime",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": true,
   "description": "Single-process reference implementation of the IrcRuntime port, backed by Maps",
   "license": "BSD-3-Clause",

package/packages/in-memory-runtime/src/in-memory-runtime.ts

@@ -27,6 +27,7 @@ import {
   type Nick,
   type RawLine,
   applyChannelDelta as applyDelta,
+  caseFold,
   createChannel,
   decideAdmission,
   toChannelSnapshot,
@@ -53,21 +54,6 @@ interface TrackedConnection {
   admissionRecordId?: string;
 }
 
-function lower(s: string): string {
-  return s.toLowerCase();
-}
-
-let disabledRecordCounter = 0;
-/**
- * Returns a unique record id for the "admission disabled" path. The id is
- * never consulted (no {@link AdmissionStats} exists), but emitting one
- * keeps {@link admitConnection}'s return shape uniform.
- */
-function _disabledRecordId(): string {
-  disabledRecordCounter += 1;
-  return `disabled-${disabledRecordCounter}`;
-}
-
 export interface InMemoryRuntimeOptions {
   clock: Clock;
   /**
@@ -113,7 +99,7 @@ export class InMemoryRuntime implements IrcRuntime {
    */
   admitConnection(ip: string, user: string | undefined): AdmissionDecision {
     if (this.admissionConfig === undefined || this.admissionStats === undefined) {
-      return { ok: true, recordId: _disabledRecordId() };
+      return { ok: true, recordId: '' };
     }
     return decideAdmission(ip, user, this.admissionStats, this.admissionConfig);
   }
@@ -185,7 +171,7 @@ export class InMemoryRuntime implements IrcRuntime {
    * return the same object.
    */
   getOrCreateChannel(name: ChanName): ChannelState {
-    const key = lower(name);
+    const key = caseFold('rfc1459', name);
     const existing = this.channels.get(key);
     if (existing !== undefined) return existing;
     const created = createChannel({
@@ -204,7 +190,7 @@ export class InMemoryRuntime implements IrcRuntime {
    * missing channel from an empty one.
    */
   getChannel(name: ChanName): ChannelState | undefined {
-    return this.channels.get(lower(name));
+    return this.channels.get(caseFold('rfc1459', name));
   }
 
   // ------------------------------------------------------------------
@@ -218,7 +204,7 @@ export class InMemoryRuntime implements IrcRuntime {
   }
 
   async broadcast(chan: ChanName, lines: RawLine[], except?: ConnId): Promise<void> {
-    const channel = this.channels.get(lower(chan));
+    const channel = this.channels.get(caseFold('rfc1459', chan));
     if (channel === undefined) return;
     for (const member of channel.members.keys()) {
       if (member === except) continue;
@@ -240,7 +226,7 @@ export class InMemoryRuntime implements IrcRuntime {
     lines: RawLine[],
     notFoundLines?: RawLine[],
   ): Promise<void> {
-    const owner = this.nicks.get(lower(nick));
+    const owner = this.nicks.get(caseFold('rfc1459', nick));
     if (owner !== undefined) {
       const conn = this.connections.get(owner);
       if (conn !== undefined) {
@@ -261,7 +247,7 @@ export class InMemoryRuntime implements IrcRuntime {
   // ------------------------------------------------------------------
 
   async reserveNick(nick: Nick, conn: ConnId): Promise<{ ok: true } | { ok: false }> {
-    const key = lower(nick);
+    const key = caseFold('rfc1459', nick);
     const existing = this.nicks.get(key);
     if (existing !== undefined && existing !== conn) {
       return { ok: false };
@@ -271,8 +257,8 @@ export class InMemoryRuntime implements IrcRuntime {
   }
 
   async changeNick(conn: ConnId, oldNick: Nick, newNick: Nick): Promise<boolean> {
-    const newKey = lower(newNick);
-    const oldKey = lower(oldNick);
+    const newKey = caseFold('rfc1459', newNick);
+    const oldKey = caseFold('rfc1459', oldNick);
     const owner = this.nicks.get(newKey);
     if (owner !== undefined && owner !== conn) {
       return false;
@@ -287,7 +273,7 @@ export class InMemoryRuntime implements IrcRuntime {
   }
 
   async releaseNick(nick: Nick): Promise<void> {
-    this.nicks.delete(lower(nick));
+    this.nicks.delete(caseFold('rfc1459', nick));
   }
 
   // ------------------------------------------------------------------
@@ -300,7 +286,7 @@ export class InMemoryRuntime implements IrcRuntime {
     // replace the stored object so subsequent snapshots see the new data
     // while any outstanding references to the prior state stay coherent.
     const next = applyDelta(channel, delta);
-    this.channels.set(lower(chan), next);
+    this.channels.set(caseFold('rfc1459', chan), next);
   }
 
   // ------------------------------------------------------------------
@@ -308,7 +294,7 @@ export class InMemoryRuntime implements IrcRuntime {
   // ------------------------------------------------------------------
 
   async lookupNick(nick: Nick): Promise<ConnId | null> {
-    return this.nicks.get(lower(nick)) ?? null;
+    return this.nicks.get(caseFold('rfc1459', nick)) ?? null;
   }
 
   async getConnectionInfo(conn: ConnId): Promise<ConnSnapshot | null> {
@@ -328,13 +314,13 @@ export class InMemoryRuntime implements IrcRuntime {
   }
 
   async getChannelSnapshot(chan: ChanName): Promise<ChanSnapshot | null> {
-    const channel = this.channels.get(lower(chan));
+    const channel = this.channels.get(caseFold('rfc1459', chan));
     if (channel === undefined) return null;
     return toChannelSnapshot(channel);
   }
 
   async getChannelConnections(chan: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>> {
-    const channel = this.channels.get(lower(chan));
+    const channel = this.channels.get(caseFold('rfc1459', chan));
     const out = new Map<ConnId, ConnectionState>();
     if (channel === undefined) return out;
     for (const connId of channel.members.keys()) {

package/packages/in-memory-runtime/tests/in-memory-runtime.test.ts

@@ -227,6 +227,14 @@ describe('InMemoryRuntime — applyChannelDelta / getChannelSnapshot', () => {
     expect(snap?.members.has('c1')).toBe(true);
   });
 
+  it('treats rfc1459 special chars [ \\ ] ^ as equal to { | } ~', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const a = rt.getOrCreateChannel('#[Foo]');
+    const b = rt.getOrCreateChannel('#{foo}');
+    expect(b).toBe(a);
+    expect(b.nameLower).toBe('#{foo}');
+  });
+
   it('returns null from getChannelSnapshot for an unknown channel', async () => {
     const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
     expect(await rt.getChannelSnapshot('#nope')).toBeNull();
@@ -614,4 +622,15 @@ describe('InMemoryRuntime — admission gate', () => {
     }
     expect(decisions.every((d) => d.ok)).toBe(true);
   });
+
+  it('returns a stable recordId when admission is disabled (no per-call minting)', () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const d1 = rt.admitConnection('1.1.1.1', 'alice');
+    const d2 = rt.admitConnection('2.2.2.2', 'bob');
+    expect(d1.ok).toBe(true);
+    expect(d2.ok).toBe(true);
+    if (d1.ok && d2.ok) {
+      expect(d1.recordId).toBe(d2.recordId);
+    }
+  });
 });

package/packages/irc-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": true,
   "description": "Platform-agnostic IRC protocol core: parser, serializer, command reducers, state shapes",
   "license": "BSD-3-Clause",
@@ -18,6 +18,10 @@
     }
   },
   "scripts": {
+    "prepare": "node scripts/generate-build-info.mjs",
+    "prebuild": "node scripts/generate-build-info.mjs",
+    "pretypecheck": "node scripts/generate-build-info.mjs",
+    "pretest": "node scripts/generate-build-info.mjs",
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "test": "vitest run",
@@ -34,6 +38,8 @@
   },
   "devDependencies": {
     "@stryker-mutator/core": "^9.6.1",
-    "@stryker-mutator/vitest-runner": "^9.6.1"
+    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@types/node": "^26.1.1",
+    "vitest": "^4.1.0"
   }
 }

package/packages/irc-core/scripts/generate-build-info.mjs

@@ -0,0 +1,31 @@
+/**
+ * Generates `src/build-info.ts` containing the build timestamp.
+ *
+ * Runs as a `prebuild` / `pretest` / `pretypecheck` / `prepare` hook so the
+ * file always exists before tsc or vitest resolves `./build-info.js` imports.
+ * The emitted file is gitignored — it is regenerated on every build so the
+ * published `dist/index.js` carries the timestamp of the build that produced
+ * it, never a stale committed value.
+ *
+ * Output shape:
+ *
+ * ```ts
+ * // AUTO-GENERATED by scripts/generate-build-info.mjs — do not edit.
+ * export const BUILD_DATE = '2024-01-01T00:00:00.000Z';
+ * ```
+ *
+ * Failures here must abort the build rather than emit a half-file: a missing
+ * or malformed `build-info.ts` would break every downstream tsc invocation.
+ */
+import { writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const target = resolve(here, '..', 'src', 'build-info.ts');
+
+const iso = new Date().toISOString();
+const contents = `// AUTO-GENERATED by scripts/generate-build-info.mjs — do not edit.\nexport const BUILD_DATE = ${JSON.stringify(iso)};\n`;
+
+writeFileSync(target, contents, 'utf8');
+console.log(`[generate-build-info] wrote ${target} (BUILD_DATE=${iso})`);

package/packages/irc-core/src/caps/capabilities.ts

@@ -13,7 +13,11 @@
 export interface Capability {
   /** Wire name (`server-time`, `sasl`, …). */
   name: string;
-  /** Optional value (`PLAIN,EXTERNAL` for `sasl`); bare name when absent. */
+  /**
+   * Optional value parameter. For `sasl` this is the base mechanism list
+   * (`PLAIN`); the {@link saslCapValue} helper upgrades it to include
+   * `EXTERNAL` when mTLS is configured for a connection.
+   */
   value?: string;
 }
 
@@ -33,10 +37,27 @@ export const SUPPORTED_CAPABILITIES: ReadonlyArray<Capability> = Object.freeze([
   { name: 'message-tags' },
   { name: 'multi-prefix' },
   { name: 'safelist' },
-  { name: 'sasl', value: 'PLAIN,EXTERNAL' },
+  { name: 'sasl', value: 'PLAIN' },
   { name: 'server-time' },
 ]);
 
+/** Wire name of the SASL capability. */
+export const SASL_CAP_NAME = 'sasl';
+
+/**
+ * Returns the `sasl` cap value to advertise given whether an mTLS identity
+ * provider is bound for the connection.
+ *
+ * PLAIN is always available. EXTERNAL is advertised only when mTLS is
+ * configured (an `MtlsIdentityProvider` is bound) so clients on
+ * non-mTLS connections do not attempt a mechanism that cannot succeed.
+ * Operators enable EXTERNAL by configuring mTLS at the edge (CF API Shield
+ * mTLS, AWS custom-domain mTLS) — no code change required.
+ */
+export function saslCapValue(hasMtls: boolean): string {
+  return hasMtls ? 'PLAIN,EXTERNAL' : 'PLAIN';
+}
+
 /** Set form for fast membership checks during `CAP REQ`. */
 export const SUPPORTED_CAP_NAMES: ReadonlySet<string> = new Set<string>(
   SUPPORTED_CAPABILITIES.map((c) => c.name),

package/packages/irc-core/src/case-fold.ts

@@ -0,0 +1,64 @@
+/**
+ * IRC case-mapping (case folding) for nick and channel-name comparison.
+ *
+ * IRC servers compare nicks and channel names case-insensitively, but the
+ * exact set of characters that fold together is advertised to clients via
+ * the `005 RPL_ISUPPORT` `CASEMAPPING=` token. This module implements the
+ * two relevant mappings:
+ *
+ *   - `ascii`   — only `A`–`Z` fold to `a`–`z`.
+ *   - `rfc1459` — `ascii` plus the four characters `[ \ ] ^` folding to
+ *     `{ | } ~` respectively (per RFC 1459 §2.2). The targets
+ *     `{ | } ~` do NOT fold further, so the fold is idempotent:
+ *     `fold(fold(s)) === fold(s)`.
+ *
+ * The fold operates on one character at a time and leaves every other byte
+ * (including all non-ASCII) unchanged. It is pure and dependency-free so it
+ * runs unchanged on every runtime (Node, Workers, Lambda).
+ *
+ * Advertised via {@link CaseMapping} and consumed by the command reducers
+ * and the reference runtime so that the advertised case-mapping and the
+ * actual folding never diverge.
+ */
+
+/** Case-mapping algorithms supported for IRC-name comparison. */
+export type CaseMapping = 'rfc1459' | 'ascii';
+
+/**
+ * Lowercases `s` according to `mapping`, returning the canonical key used
+ * for case-insensitive nick and channel comparison.
+ *
+ * @param mapping  `rfc1459` (default behaviour everywhere in this server) or
+ *                 `ascii` (a strict subset — useful for strict-ASCII tests).
+ * @param s        The nick or channel name to fold.
+ */
+export function caseFold(mapping: CaseMapping, s: string): string {
+  let out = '';
+  for (let i = 0; i < s.length; i += 1) {
+    out += foldChar(mapping, s.charCodeAt(i));
+  }
+  return out;
+}
+
+/** Folds a single UTF-16 code unit per the active mapping. */
+function foldChar(mapping: CaseMapping, code: number): string {
+  if (code >= 0x41 && code <= 0x5a) {
+    // A–Z → a–z
+    return String.fromCharCode(code + 0x20);
+  }
+  if (mapping === 'rfc1459') {
+    switch (code) {
+      case 0x5b:
+        return '{'; // [ → {
+      case 0x5c:
+        return '|'; // \ → |
+      case 0x5d:
+        return '}'; // ] → }
+      case 0x5e:
+        return '~'; // ^ → ~
+      default:
+        break;
+    }
+  }
+  return String.fromCharCode(code);
+}

package/packages/irc-core/src/cloak.ts

@@ -11,7 +11,7 @@
  *
  * Implementation note: this uses a self-contained FNV-1a 32-bit hash plus a
  * short base32 encoding so the module stays pure-TS and runs unchanged on
- * Node 20, Cloudflare Workers, and Lambda. It is NOT a cryptographic MAC:
+ * Node 24, Cloudflare Workers, and Lambda. It is NOT a cryptographic MAC:
  * an attacker who learns one cloak cannot recover the secret, but a
  * determined attacker with the secret can forge cloaks. Deployments that
  * need stronger unforgeability should override this module.