serverless-ircd 0.5.0 → 0.6.0

package/packages/cf-adapter/tests/registry-do.test.ts

@@ -53,6 +53,7 @@ interface RegistryRpc {
   changeNick(conn: string, oldNick: string, newNick: string): Promise<boolean>;
   releaseNick(nick: string): Promise<void>;
   lookupNick(nick: string): Promise<string | null>;
+  listEntries(): Promise<Array<[nickLower: string, connId: string]>>;
 }
 
 function rpc(stub: DurableObjectStub): RegistryRpc {
@@ -333,3 +334,106 @@ describe('RegistryDO — shard isolation', () => {
     expect(await rpc(i).lookupNick('in-shard-31')).toBeNull();
   });
 });
+
+// ---------------------------------------------------------------------------
+// changeNick — direct contract tests (sharding is a CfRuntime concern; the
+// DO method itself operates on whatever keys it is given, so we address a
+// single DO instance directly to exercise every branch without depending on
+// the FNV-1a hash landing two nicks in the same shard).
+// ---------------------------------------------------------------------------
+
+describe('RegistryDO — changeNick branch coverage (direct on one shard)', () => {
+  // Pin every test to a single, stable shard instance. The DO method is
+  // agnostic to which shard it lives on; what matters is the storage
+  // state we put in place before the call.
+  const shard = () => shardByIndex(1);
+
+  it('returns false when the new nick is held by a different conn', async () => {
+    const s = shard();
+    // Seed storage so both `taken` and `current` are owned by different
+    // conns on this same DO.
+    expect(await rpc(s).reserveNick('taken-new', 'conn-owner')).toEqual({ ok: true });
+    expect(await rpc(s).reserveNick('current-old', 'conn-changer')).toEqual({ ok: true });
+
+    const ok = await rpc(s).changeNick('conn-changer', 'current-old', 'taken-new');
+    expect(ok).toBe(false);
+    // State untouched: owners stay as they were.
+    expect(await rpc(s).lookupNick('taken-new')).toBe('conn-owner');
+    expect(await rpc(s).lookupNick('current-old')).toBe('conn-changer');
+  });
+
+  it('clears the old nick when it still points at the caller', async () => {
+    const s = shard();
+    expect(await rpc(s).reserveNick('cn-clear-old', 'conn-self')).toEqual({ ok: true });
+
+    const ok = await rpc(s).changeNick('conn-self', 'cn-clear-old', 'cn-clear-new');
+    expect(ok).toBe(true);
+    expect(await rpc(s).lookupNick('cn-clear-old')).toBeNull();
+    expect(await rpc(s).lookupNick('cn-clear-new')).toBe('conn-self');
+  });
+
+  it('leaves a stale old nick alone when it no longer points at the caller', async () => {
+    // Crash-recovery / race defence: another conn grabbed `old` between
+    // our reserve and our changeNick. The conditional delete must not
+    // clobber that third party.
+    const s = shard();
+    // `old` is currently held by `conn-other`, not by `conn-caller`.
+    expect(await rpc(s).reserveNick('cn-stale-old', 'conn-other')).toEqual({ ok: true });
+
+    const ok = await rpc(s).changeNick('conn-caller', 'cn-stale-old', 'cn-stale-new');
+    expect(ok).toBe(true);
+    // New nick reserved for the caller...
+    expect(await rpc(s).lookupNick('cn-stale-new')).toBe('conn-caller');
+    // ...but `old` is untouched because it never pointed at the caller.
+    expect(await rpc(s).lookupNick('cn-stale-old')).toBe('conn-other');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// listEntries — backs the global WALLOPS fan-out (CfRuntime.broadcastWallops
+// walks every shard via this method).
+// ---------------------------------------------------------------------------
+
+describe('RegistryDO — listEntries', () => {
+  it('returns an empty array for a fresh shard', async () => {
+    expect(await rpc(shardByIndex(2)).listEntries()).toEqual([]);
+  });
+
+  it('enumerates every (nickLower, connId) pair in this shard', async () => {
+    const s = shardByIndex(3);
+    await rpc(s).reserveNick('Alice', 'conn-a');
+    await rpc(s).reserveNick('Bob', 'conn-b');
+    await rpc(s).reserveNick('Carol', 'conn-c');
+
+    const entries = await rpc(s).listEntries();
+    // Keys are lowercased in storage; the strip recovers the lowercased
+    // nick (matches what CfRuntime expects when deduping conn ids).
+    const sorted = [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    expect(sorted).toEqual([
+      ['alice', 'conn-a'],
+      ['bob', 'conn-b'],
+      ['carol', 'conn-c'],
+    ]);
+  });
+
+  it('reflects releases: a freed nick drops out of the listing', async () => {
+    const s = shardByIndex(4);
+    await rpc(s).reserveNick('keep', 'conn-k');
+    await rpc(s).reserveNick('drop', 'conn-d');
+    await rpc(s).releaseNick('drop');
+
+    const entries = await rpc(s).listEntries();
+    expect(entries).toEqual([['keep', 'conn-k']]);
+  });
+
+  it('strips the storage prefix so callers see a bare nickLower', async () => {
+    const s = shardByIndex(5);
+    await rpc(s).reserveNick('prefixed', 'conn-p');
+    const entries = await rpc(s).listEntries();
+    const nickLower = entries[0]?.[0];
+    // The internal key is `nick:prefixed`; the public API must not leak
+    // that implementation detail.
+    expect(nickLower).toBe('prefixed');
+    expect(nickLower?.startsWith('nick:')).toBe(false);
+  });
+});

package/packages/cf-adapter/tests/serialize.test.ts

@@ -0,0 +1,308 @@
+/**
+ * `serialize` / `deserialize` / `migrate`.
+ *
+ * These helpers bridge {@link ConnectionState} (which carries `Set` and
+ * `Map` fields that degrade under `JSON.stringify`) and the JSON-safe
+ * {@link PersistedConnectionState} shape stored in DO transactional KV.
+ *
+ * Coverage focus: every optional-field branch in both directions, the
+ * `secure` / `userModes.tls` backfill paths in `migrate`, and the
+ * rejection paths (non-object record, too-new version).
+ */
+
+import { type ConnectionState, createConnection } from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import { PERSISTED_STATE_VERSION, deserialize, migrate, serialize } from '../src/serialize';
+
+/** Builds a fully-populated connection state for round-trip assertions. */
+function fullState(): ConnectionState {
+  const s = createConnection({ id: 'conn-1', connectedSince: 100 });
+  s.registration = 'registered';
+  s.capNegotiating = false;
+  s.secure = true;
+  s.nick = 'Alice';
+  s.user = 'alice';
+  s.host = 'example.com';
+  s.realname = 'Alice Example';
+  s.passAttempt = 'hunter2';
+  s.account = 'alice-account';
+  s.away = 'brb';
+  s.caps = new Set(['server-time', 'message-tags']);
+  s.joinedChannels = new Set(['#one', '#two']);
+  s.userModes = {
+    invisible: true,
+    oper: false,
+    wallops: true,
+    serverNotices: false,
+    tls: true,
+  };
+  s.lastSeen = 200;
+  return s;
+}
+
+describe('serialize — round trip', () => {
+  it('survives serialize → deserialize for a fully-populated state', () => {
+    const original = fullState();
+    const round = deserialize(serialize(original));
+    // Sets are rebuilt with the same members.
+    expect(round.caps).toEqual(new Set(['server-time', 'message-tags']));
+    expect(round.joinedChannels).toEqual(new Set(['#one', '#two']));
+    // Optional fields preserved.
+    expect(round.nick).toBe('Alice');
+    expect(round.user).toBe('alice');
+    expect(round.host).toBe('example.com');
+    expect(round.realname).toBe('Alice Example');
+    expect(round.passAttempt).toBe('hunter2');
+    expect(round.account).toBe('alice-account');
+    expect(round.away).toBe('brb');
+    // userModes cloned (mutating the round trip must not leak back).
+    expect(round.userModes).toEqual(original.userModes);
+    expect(round.userModes).not.toBe(original.userModes);
+    expect(round.secure).toBe(true);
+  });
+
+  it('is JSON-stable: serialize → JSON.stringify → JSON.parse → deserialize', () => {
+    // This is the actual production path through DO storage: the runtime
+    // structured-clones the value, but the persisted shape must also be
+    // JSON-tolerant for older storage rows and snapshots written to R2.
+    const original = fullState();
+    const json = JSON.stringify(serialize(original));
+    const round = deserialize(JSON.parse(json));
+    expect(round.caps).toEqual(original.caps);
+    expect(round.nick).toBe(original.nick);
+    expect(round.away).toBe(original.away);
+  });
+
+  it('stamps the current persisted schema version', () => {
+    expect(serialize(fullState()).version).toBe(PERSISTED_STATE_VERSION);
+  });
+});
+
+describe('serialize — optional-field branches', () => {
+  it('omits host when undefined', () => {
+    const s = createConnection({ id: 'c', connectedSince: 0 });
+    s.nick = 'n';
+    expect(serialize(s).host).toBeUndefined();
+  });
+
+  it('omits passAttempt when undefined', () => {
+    const s = createConnection({ id: 'c', connectedSince: 0 });
+    expect(serialize(s).passAttempt).toBeUndefined();
+  });
+
+  it('omits away when undefined', () => {
+    const s = createConnection({ id: 'c', connectedSince: 0 });
+    expect(serialize(s).away).toBeUndefined();
+  });
+
+  it('clones caps and joinedChannels arrays away from the live Set', () => {
+    const s = createConnection({ id: 'c', connectedSince: 0 });
+    s.caps = new Set(['a']);
+    s.joinedChannels = new Set(['#x']);
+    const out = serialize(s);
+    expect(out.caps).toEqual(['a']);
+    expect(out.joinedChannels).toEqual(['#x']);
+  });
+});
+
+describe('deserialize — optional-field branches', () => {
+  it('populates host when the persisted record carries it', () => {
+    const s = createConnection({ id: 'c', connectedSince: 0 });
+    s.host = 'host.example';
+    expect(deserialize(serialize(s)).host).toBe('host.example');
+  });
+
+  it('populates passAttempt when the persisted record carries it', () => {
+    const s = createConnection({ id: 'c', connectedSince: 0 });
+    s.passAttempt = 'pw';
+    expect(deserialize(serialize(s)).passAttempt).toBe('pw');
+  });
+
+  it('populates account when the persisted record carries it', () => {
+    const s = createConnection({ id: 'c', connectedSince: 0 });
+    s.account = 'acc';
+    expect(deserialize(serialize(s)).account).toBe('acc');
+  });
+
+  it('populates away when the persisted record carries it', () => {
+    const s = createConnection({ id: 'c', connectedSince: 0 });
+    s.away = 'afk';
+    expect(deserialize(serialize(s)).away).toBe('afk');
+  });
+
+  it('leaves optional fields absent on a minimal pre-registration state', () => {
+    const s = createConnection({ id: 'c', connectedSince: 0 });
+    const round = deserialize(serialize(s));
+    expect(round.nick).toBeUndefined();
+    expect(round.host).toBeUndefined();
+    expect(round.away).toBeUndefined();
+    expect(round.account).toBeUndefined();
+    expect(round.passAttempt).toBeUndefined();
+  });
+});
+
+describe('migrate — backfills additive fields', () => {
+  it('defaults `secure` to false when the field is absent', () => {
+    // Pre-feature record: no `secure` key at all.
+    const legacy = {
+      version: 1,
+      id: 'c',
+      registration: 'registered' as const,
+      capNegotiating: false,
+      caps: [],
+      joinedChannels: [],
+      userModes: {
+        invisible: false,
+        oper: false,
+        wallops: false,
+        serverNotices: false,
+      },
+      lastSeen: 0,
+      connectedSince: 0,
+    };
+    const migrated = migrate(legacy);
+    expect(migrated.secure).toBe(false);
+    // The mutation landed on the original object reference (defensive
+    // backfill writes through to the record).
+    expect((legacy as Record<string, unknown>).secure).toBe(false);
+  });
+
+  it('defaults `userModes.tls` to false when the field is absent', () => {
+    const legacy = {
+      version: 1,
+      id: 'c',
+      registration: 'registered' as const,
+      capNegotiating: false,
+      caps: [],
+      joinedChannels: [],
+      userModes: {
+        invisible: false,
+        oper: false,
+        wallops: false,
+        serverNotices: false,
+      },
+      lastSeen: 0,
+      connectedSince: 0,
+    };
+    const migrated = migrate(legacy);
+    expect(migrated.userModes.tls).toBe(false);
+  });
+
+  it('leaves an explicit `secure: true` untouched', () => {
+    const rec = {
+      version: 1,
+      id: 'c',
+      registration: 'registered' as const,
+      capNegotiating: false,
+      secure: true,
+      caps: [],
+      joinedChannels: [],
+      userModes: {
+        invisible: false,
+        oper: false,
+        wallops: false,
+        serverNotices: false,
+        tls: true,
+      },
+      lastSeen: 0,
+      connectedSince: 0,
+    };
+    expect(migrate(rec).secure).toBe(true);
+    expect(migrate(rec).userModes.tls).toBe(true);
+  });
+
+  it('tolerates a missing `userModes` object without throwing', () => {
+    // A record corrupted in storage (or hand-built by an older code
+    // path) might not carry userModes at all. Migrate must not crash.
+    const rec = {
+      version: 1,
+      id: 'c',
+      registration: 'registered' as const,
+      capNegotiating: false,
+      caps: [],
+      joinedChannels: [],
+      lastSeen: 0,
+      connectedSince: 0,
+    };
+    expect(() => migrate(rec)).not.toThrow();
+  });
+});
+
+describe('migrate — rejection paths', () => {
+  it('rejects a non-object record', () => {
+    for (const bad of [null, 'string', 42, true, undefined]) {
+      expect(() => migrate(bad)).toThrow(/not an object/u);
+    }
+  });
+
+  it('rejects an array record (arrays are not plain objects)', () => {
+    expect(() => migrate([])).toThrow(/not an object/u);
+  });
+
+  it('rejects a record persisted with a newer schema version', () => {
+    const future = {
+      version: PERSISTED_STATE_VERSION + 1,
+      id: 'c',
+      registration: 'registered' as const,
+      capNegotiating: false,
+      caps: [],
+      joinedChannels: [],
+      userModes: {
+        invisible: false,
+        oper: false,
+        wallops: false,
+        serverNotices: false,
+        tls: false,
+      },
+      lastSeen: 0,
+      connectedSince: 0,
+    };
+    expect(() => migrate(future)).toThrow(/newer than/u);
+  });
+
+  it('treats a missing version as the legacy default (0)', () => {
+    // No `version` field — old shape. Migrate must accept it rather
+    // than fail the boot path; the backfill covers the additive keys.
+    const legacy = {
+      id: 'c',
+      registration: 'registered' as const,
+      capNegotiating: false,
+      caps: [],
+      joinedChannels: [],
+      userModes: {
+        invisible: false,
+        oper: false,
+        wallops: false,
+        serverNotices: false,
+      },
+      lastSeen: 0,
+      connectedSince: 0,
+    };
+    expect(() => migrate(legacy)).not.toThrow();
+  });
+});
+
+describe('deserialize — migrate integration', () => {
+  it('backfills `secure` and `userModes.tls` on a legacy record, then materializes', () => {
+    const legacy = {
+      id: 'c',
+      registration: 'registered' as const,
+      capNegotiating: false,
+      caps: ['server-time'],
+      joinedChannels: ['#x'],
+      userModes: {
+        invisible: false,
+        oper: false,
+        wallops: true,
+        serverNotices: false,
+      },
+      lastSeen: 5,
+      connectedSince: 1,
+    };
+    const state = deserialize(legacy);
+    expect(state.secure).toBe(false);
+    expect(state.userModes.tls).toBe(false);
+    expect(state.userModes.wallops).toBe(true);
+    expect(state.caps).toEqual(new Set(['server-time']));
+  });
+});

package/packages/cf-adapter/vitest.config.ts

@@ -5,7 +5,7 @@ export default defineConfig({
   test: {
     include: ['tests/**/*.test.ts'],
     coverage: {
-      provider: 'v8',
+      provider: 'istanbul',
       all: false,
       include: ['src/**/*.ts'],
       exclude: ['src/**/index.ts'],

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

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

package/packages/irc-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": true,
   "description": "Platform-agnostic IRC protocol core: parser, serializer, command reducers, state shapes",
   "license": "BSD-3-Clause",

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

@@ -21,29 +21,63 @@ export interface Capability {
   value?: string;
 }
 
+/** Wire name of the SASL capability. */
+export const SASL_CAP_NAME = 'sasl';
+
+/** Wire name of the IRCv3 `draft/multiline` capability. */
+export const MULTILINE_CAP_NAME = 'draft/multiline';
+
+/** Wire name of the IRCv3 `draft/read-marker` capability. */
+export const READ_MARKER_CAP_NAME = 'draft/read-marker';
+
+/** Wire name of the IRCv3 `draft/pre-away` capability. */
+export const PRE_AWAY_CAP_NAME = 'draft/pre-away';
+
+/**
+ * Default byte budget advertised in `draft/multiline=<n>` and enforced on
+ * every finalized multi-line batch. Mirrors the IRCv3 spec's canonical
+ * recommendation; deployments override via `ServerConfig.multilineMaxBytes`.
+ */
+export const DEFAULT_MULTILINE_MAX_BYTES = 4096;
+
+/**
+ * Builds the `draft/multiline` cap *value* (the substring after `=`) for the
+ * advertised byte budget. The {@link CapReducer} and the multi-line reducer
+ * share this helper so the wire token has one source of truth.
+ */
+export function multilineCapValue(maxBytes: number): string {
+  return String(maxBytes);
+}
+
 /**
  * Every cap advertised by this server in PLAN §3, in canonical (alpha) order
  * so wire output is deterministic across runs.
  */
 export const SUPPORTED_CAPABILITIES: ReadonlyArray<Capability> = Object.freeze([
+  { name: 'account-notify' },
   { name: 'account-tag' },
   { name: 'away-notify' },
   { name: 'batch' },
   { name: 'chghost' },
   { name: 'draft/chathistory' },
+  { name: 'draft/multiline', value: multilineCapValue(DEFAULT_MULTILINE_MAX_BYTES) },
+  { name: 'draft/pre-away' },
+  { name: 'draft/read-marker' },
+  { name: 'draft/typing' },
   { name: 'echo-message' },
   { name: 'extended-join' },
   { name: 'invite-notify' },
+  { name: 'labeled-response' },
   { name: 'message-tags' },
+  { name: 'msgid' },
+  { name: 'monitor' },
   { name: 'multi-prefix' },
   { name: 'safelist' },
   { name: 'sasl', value: 'PLAIN' },
   { name: 'server-time' },
+  { name: 'standard-replies' },
 ]);
 
-/** 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.

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

@@ -1 +1,2 @@
 export * from './capabilities.js';
+export * from './sts.js';

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

@@ -0,0 +1,84 @@
+/**
+ * IRCv3 `sts` (Strict Transport Security) policy.
+ *
+ * Spec: https://ircv3.net/specs/extensions/sts
+ *
+ * The server advertises an `sts` capability whose value is a
+ * comma-separated `key=value` policy. Compliant clients inspect the
+ * policy and:
+ *
+ *   - On a plaintext connection: reconnect over TLS to the advertised
+ *     `port` and pin it for `duration` seconds. `preload` (optional)
+ *     signals the client may hard-code the policy into a preload list.
+ *   - On a TLS connection: only the `duration` is locked in — `port`
+ *     is meaningless once the client is already on the secure listener,
+ *     and `preload` is an upgrade-time directive.
+ *
+ * Config-driven only: there is no per-connection protocol state. The
+ * deployment supplies the policy through {@link StsConfig} on
+ * {@link ServerConfig}; when omitted entirely the cap is not advertised.
+ */
+
+/**
+ * IRC-over-TLS port per RFC 7193 / IRCv3 STS spec examples. Used as the
+ * fallback `port` when a deployment turns on STS without pinning a port.
+ */
+export const DEFAULT_STS_PORT = 6697;
+
+/**
+ * Default pin duration (30 days, in seconds). Mirrors the IRCv3 spec's
+ * canonical example and what mainstream IRC networks publish. Deployments
+ * override via {@link StsConfig.duration}.
+ */
+export const DEFAULT_STS_DURATION_SECONDS = 30 * 24 * 60 * 60;
+
+/** Wire name of the STS capability. */
+export const STS_CAP_NAME = 'sts';
+
+/**
+ * Raw STS policy as supplied by {@link ServerConfig}. Every field is
+ * optional; {@link stsCapValue} applies the documented defaults when a
+ * field is omitted. `undefined` (the whole object) disables STS.
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true` so the
+ * parsed config is structurally assignable here.
+ */
+export interface StsPolicy {
+  /** Pin duration in seconds. Defaults to 30 days. */
+  readonly duration?: number;
+  /** TLS listener port advertised on plaintext connections. Defaults to 6697. */
+  readonly port?: number;
+  /** Optional preload directive (plaintext advertisements only). */
+  readonly preload?: boolean | undefined;
+}
+
+/**
+ * Builds the IRCv3 `sts` capability *value* (the substring after `sts=`)
+ * for the given policy and transport.
+ *
+ * Returns `undefined` when STS is disabled (`policy` undefined), so the cap
+ * table consumer can omit the token entirely from `CAP LS`.
+ *
+ * On a plaintext transport the full policy is advertised:
+ *   `duration=<seconds>,port=<tls-port>[,preload]`
+ *
+ * On a TLS transport only `duration=<seconds>` is sent — the port is
+ * meaningless (the client is already on the secure listener) and
+ * `preload` is an upgrade-time directive that does not apply.
+ *
+ * Missing `duration`/`port` fall back to {@link DEFAULT_STS_DURATION_SECONDS}
+ * and {@link DEFAULT_STS_PORT} so a deployment can enable STS with a bare
+ * `{}` policy and still publish a sensible value.
+ */
+export function stsCapValue(policy: StsPolicy | undefined, secure: boolean): string | undefined {
+  if (policy === undefined) return undefined;
+  const duration = policy.duration ?? DEFAULT_STS_DURATION_SECONDS;
+  if (secure) {
+    return `duration=${duration}`;
+  }
+  const port = policy.port ?? DEFAULT_STS_PORT;
+  const parts = [`duration=${duration}`, `port=${port}`];
+  if (policy.preload === true) parts.push('preload');
+  return parts.join(',');
+}

package/packages/irc-core/src/commands/account-notify.ts

@@ -0,0 +1,53 @@
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { ChanName } from '../state/channel.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+
+export interface AccountNotifyInput {
+  conn: ConnectionState;
+  /**
+   * New account name on login. Pass `undefined` to signal a logout, which
+   * serializes the account field as `*` per IRCv3 `account-notify`.
+   */
+  account?: string | undefined;
+}
+
+/**
+ * Builds the cap-split Broadcast effects that announce an `ACCOUNT` login
+ * (or logout) to peers in every shared channel.
+ *
+ * Mirrors the `emitChghost` broadcast helper: each joined channel produces
+ * one {@link Effect.broadcast} carrying empty `lines` (so non-cap peers
+ * receive nothing) and the `ACCOUNT` line in `capLines` for peers that
+ * negotiated `account-notify`. The sender is excluded via `except` unless
+ * they negotiated `echo-message`, in which case a single echo
+ * {@link Effect.send} is appended (one echo regardless of how many shared
+ * channels the user occupies).
+ *
+ * Returns `[]` before registration completes or when the connection holds
+ * no joined channels — there is no audience to notify.
+ */
+export function emitAccountNotify(input: AccountNotifyInput): EffectType[] {
+  const { conn, account } = input;
+
+  if (conn.registration !== 'registered') return [];
+  if (conn.joinedChannels.size === 0) return [];
+
+  const source = hostmaskOf(conn) ?? conn.nick ?? '?';
+  const accountField = account ?? '*';
+  const line: RawLine = { text: `:${source} ACCOUNT ${accountField}` };
+
+  const effects: EffectType[] = [];
+  for (const chan of conn.joinedChannels) {
+    effects.push(Effect.broadcast(chan as ChanName, [], conn.id, 'account-notify', [line]));
+  }
+
+  // IRCv3 echo-message: the sender observes its own ACCOUNT change exactly
+  // once, regardless of how many channels it shares with peers.
+  if (conn.caps.has('echo-message')) {
+    effects.push(Effect.send(conn.id, [line]));
+  }
+
+  return effects;
+}