serverless-ircd 0.1.0 → 0.3.0

package/packages/cf-adapter/src/channel-do.ts

@@ -46,7 +46,7 @@ import {
   createChannel,
   toSnapshot,
 } from '@serverless-ircd/irc-core';
-import type { Env } from './env.js';
+import type { ChannelRegistryRpc, Env } from './env.js';
 
 /** Storage key under which the per-channel state is persisted. */
 const STATE_STORAGE_KEY = 'channel-state';
@@ -129,8 +129,10 @@ export class ChannelDO extends DurableObject<Env> {
    */
   async applyChannelDelta(delta: ChannelDelta): Promise<void> {
     const state = await this.loadState();
+    const wasEmpty = state.members.size === 0;
     const next = applyChannelDelta(state, delta);
     await this.persistState(next);
+    await this.syncRegistry(wasEmpty, next);
   }
 
   // -------------------------------------------------------------------------
@@ -160,10 +162,12 @@ export class ChannelDO extends DurableObject<Env> {
     const payload = lines.map((text) => ({ text }));
     const pruned = await this.fanoutAndCollect(state, payload, except);
     if (pruned.length > 0) {
+      const wasEmpty = false;
       const next = applyChannelDelta(state, {
         memberships: pruned.map((conn) => ({ type: 'remove' as const, conn })),
       });
       await this.persistState(next);
+      await this.syncRegistry(wasEmpty, next);
     }
   }
 
@@ -182,10 +186,12 @@ export class ChannelDO extends DurableObject<Env> {
     // OPEN-socket count without sending bytes).
     const pruned = await this.fanoutAndCollect(state, [], undefined);
     if (pruned.length > 0) {
+      const wasEmpty = false;
       const next = applyChannelDelta(state, {
         memberships: pruned.map((conn) => ({ type: 'remove' as const, conn })),
       });
       await this.persistState(next);
+      await this.syncRegistry(wasEmpty, next);
     }
     return pruned.length;
   }
@@ -206,6 +212,16 @@ export class ChannelDO extends DurableObject<Env> {
     return toDto(state);
   }
 
+  /**
+   * Returns the ConnIds of every member of this channel. Used by
+   * {@link CfRuntime.getChannelConnections} to enumerate the
+   * ConnectionStates of all members (for WHO).
+   */
+  async listMembers(): Promise<string[]> {
+    const state = await this.loadState();
+    return Array.from(state.members.keys());
+  }
+
   // -------------------------------------------------------------------------
   // Internal helpers
   // -------------------------------------------------------------------------
@@ -289,6 +305,29 @@ export class ChannelDO extends DurableObject<Env> {
     }
   }
 
+  /**
+   * Keeps the channel registry in sync: registers the channel when it
+   * transitions from empty to non-empty, unregisters on the reverse
+   * transition. Called after every membership-mutating path so the
+   * registry always reflects the live channel set.
+   */
+  private async syncRegistry(wasEmpty: boolean, next: ChannelState): Promise<void> {
+    const isEmpty = next.members.size === 0;
+    if (wasEmpty && !isEmpty) {
+      await this.channelRegistry().register(next.nameLower);
+    } else if (!wasEmpty && isEmpty) {
+      await this.channelRegistry().unregister(next.nameLower);
+    }
+  }
+
+  /** Returns the channel registry DO RPC stub. */
+  private channelRegistry(): ChannelRegistryRpc {
+    const stub = this.env.CHANNEL_REGISTRY_DO.get(
+      this.env.CHANNEL_REGISTRY_DO.idFromName('channels'),
+    );
+    return stub as unknown as ChannelRegistryRpc;
+  }
+
   // -------------------------------------------------------------------------
   // Test hooks (only invoked from `runInDurableObject` in tests)
   // -------------------------------------------------------------------------

package/packages/cf-adapter/src/channel-registry-do.ts

@@ -0,0 +1,58 @@
+/**
+ * `ChannelRegistryDO` — Cloudflare Durable Object that tracks the set
+ * of all channel names.
+ *
+ * A single DO instance (keyed by the literal name `channels`) maintains
+ * the complete channel-name set so {@link CfRuntime.listChannels} can
+ * enumerate every channel without scanning each per-channel DO
+ * individually.
+ *
+ * Storage layout:
+ *   - One key per channel: `chan:<lower>` → `1`
+ *
+ * Per-channel keys keep storage proportional to the live channel count
+ * and let individual register/unregister calls stay O(1).
+ *
+ * RPC surface — implements {@link ChannelRegistryRpc}. The ChannelDO
+ * calls `register` / `unregister` whenever its membership transitions
+ * between empty and non-empty; CfRuntime calls `list` for LIST.
+ */
+
+import { DurableObject } from 'cloudflare:workers';
+import type { ChannelRegistryRpc } from './env.js';
+
+/** Storage key prefix for per-channel entries. */
+const CHAN_KEY_PREFIX = 'chan:';
+
+/** Returns the storage key for `nameLower`. */
+function chanKey(nameLower: string): string {
+  return `${CHAN_KEY_PREFIX}${nameLower}`;
+}
+
+/**
+ * Channel registry authority.
+ *
+ * The class is exported as a binding target in `wrangler.toml`; the
+ * Workers runtime instantiates it with `(ctx, env)`.
+ */
+export class ChannelRegistryDO extends DurableObject implements ChannelRegistryRpc {
+  /** Adds `name` to the registry (idempotent). */
+  async register(name: string): Promise<void> {
+    await this.ctx.storage.put(chanKey(name.toLowerCase()), 1);
+  }
+
+  /** Removes `name` from the registry (idempotent). */
+  async unregister(name: string): Promise<void> {
+    await this.ctx.storage.delete(chanKey(name.toLowerCase()));
+  }
+
+  /** Returns all registered channel names (lowercased). */
+  async list(): Promise<string[]> {
+    const entries = await this.ctx.storage.list({ prefix: CHAN_KEY_PREFIX });
+    const names: string[] = [];
+    for (const key of entries.keys()) {
+      names.push(key.slice(CHAN_KEY_PREFIX.length));
+    }
+    return names;
+  }
+}

package/packages/cf-adapter/src/config-loader.ts

@@ -0,0 +1,135 @@
+/**
+ * Cloudflare Workers config loader.
+ *
+ * Adapts the platform-native env vars (Workers `vars` in `wrangler.toml`
+ * or per-environment secrets) into the shared `ServerConfigSchema` from
+ * `irc-core`. Both adapters (CF + AWS) consume the same schema; only the
+ * env-shape mapping differs per platform.
+ *
+ * String env vars are coerced into the schema's expected types here so
+ * operators can express every config knob as a wrangler var/secret
+ * without per-type plumbing in the worker.
+ */
+
+import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
+
+/**
+ * The subset of the Workers `Env` that this loader reads. Mirrors the
+ * production {@link Env} in `env.ts` plus the optional knobs the schema
+ * recognises. Optional members are omitted from the input object when
+ * undefined so the schema's defaults apply.
+ */
+export interface CfConfigEnv {
+  SERVER_NAME?: string;
+  NETWORK_NAME?: string;
+  MOTD_LINES?: string;
+  MAX_CLIENTS?: string;
+  CHANNEL_PREFIXES?: string;
+  OPER_USER?: string;
+  OPER_PASSWORD?: string;
+  MAX_CHANNELS_PER_USER?: string;
+  MAX_TARGETS_PER_COMMAND?: string;
+  NICK_LEN?: string;
+  CHANNEL_LEN?: string;
+  TOPIC_LEN?: string;
+  MAX_LIST_ENTRIES?: string;
+  QUIT_MESSAGE?: string;
+  /**
+   * SASL PLAIN accounts. Newline-delimited `username:password` pairs.
+   * Parsed into the `saslAccounts` config field so the config-driven
+   * path (vs the connection-do's direct env read) stays consistent.
+   */
+  SASL_ACCOUNTS?: string;
+}
+
+/**
+ * Builds the input object the shared schema expects from a Workers env.
+ *
+ * Helper extracted so the assemble→parse boundary is unit-testable in
+ * isolation: the produced input is a plain object that exactly matches
+ * `ServerConfigSchema`'s shape (strings converted to numbers / arrays
+ * as needed). Missing optional fields are kept out so the schema
+ * defaults kick in.
+ */
+function buildConfigInput(env: CfConfigEnv): Record<string, unknown> {
+  const input: Record<string, unknown> = {
+    serverName: env.SERVER_NAME,
+    networkName: env.NETWORK_NAME,
+  };
+  if (env.MOTD_LINES !== undefined && env.MOTD_LINES.length > 0) {
+    input.motdLines = env.MOTD_LINES.split('\n');
+  }
+  if (env.MAX_CLIENTS !== undefined) {
+    input.maxClients = Number.parseInt(env.MAX_CLIENTS, 10);
+  }
+  if (env.CHANNEL_PREFIXES !== undefined) {
+    input.channelPrefixes = env.CHANNEL_PREFIXES;
+  }
+  if (env.OPER_USER !== undefined || env.OPER_PASSWORD !== undefined) {
+    // Build the cred object from whatever was supplied; the schema
+    // surfaces a `user`/`password` error if only one half was provided.
+    input.operCreds = [
+      {
+        user: env.OPER_USER ?? '',
+        password: env.OPER_PASSWORD ?? '',
+      },
+    ];
+  }
+  if (env.MAX_CHANNELS_PER_USER !== undefined) {
+    input.maxChannelsPerUser = Number.parseInt(env.MAX_CHANNELS_PER_USER, 10);
+  }
+  if (env.MAX_TARGETS_PER_COMMAND !== undefined) {
+    input.maxTargetsPerCommand = Number.parseInt(env.MAX_TARGETS_PER_COMMAND, 10);
+  }
+  if (env.NICK_LEN !== undefined) {
+    input.nickLen = Number.parseInt(env.NICK_LEN, 10);
+  }
+  if (env.CHANNEL_LEN !== undefined) {
+    input.channelLen = Number.parseInt(env.CHANNEL_LEN, 10);
+  }
+  if (env.TOPIC_LEN !== undefined) {
+    input.topicLen = Number.parseInt(env.TOPIC_LEN, 10);
+  }
+  if (env.MAX_LIST_ENTRIES !== undefined) {
+    input.maxListEntries = Number.parseInt(env.MAX_LIST_ENTRIES, 10);
+  }
+  if (env.QUIT_MESSAGE !== undefined) {
+    input.quitMessage = env.QUIT_MESSAGE;
+  }
+  if (env.SASL_ACCOUNTS !== undefined && env.SASL_ACCOUNTS.length > 0) {
+    input.saslAccounts = parseSaslAccountsLines(env.SASL_ACCOUNTS);
+  }
+  return input;
+}
+
+/**
+ * Parses a newline-delimited `username:password` string into the config's
+ * `saslAccounts` shape. Malformed entries are skipped so a trailing
+ * newline or partial edit does not break boot.
+ */
+function parseSaslAccountsLines(raw: string): Array<{ username: string; password: string }> {
+  const out: Array<{ username: string; password: string }> = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue;
+    const username = trimmed.slice(0, sep);
+    const password = trimmed.slice(sep + 1);
+    if (username.length === 0 || password.length === 0) continue;
+    out.push({ username, password });
+  }
+  return out;
+}
+
+/**
+ * Loads and validates the server config from a Cloudflare Workers env.
+ *
+ * Wraps the shared {@link parseServerConfig} so a single boot-time
+ * failure mode covers every adapter: invalid config throws a readable
+ * `Error` listing every offending field, surfacing the problem before
+ * any connection is accepted.
+ */
+export function loadServerConfigFromCfEnv(env: CfConfigEnv): ParsedServerConfig {
+  return parseServerConfig(buildConfigInput(env));
+}

package/packages/cf-adapter/src/connection-do.ts

@@ -29,14 +29,22 @@
 
 import { DurableObject } from 'cloudflare:workers';
 import {
+  type AccountStore,
   type ChanName,
   type ChannelState,
   type Clock,
   type ConnId,
   type ConnectionState,
+  ConsoleLogger,
   type IdFactory,
+  InMemoryAccountStore,
+  InMemoryMessageStore,
+  LogLevel,
+  type Logger,
+  type MessageStore,
   type MotdProvider,
   type RawLine,
+  type SaslAccountCredential,
   type ServerConfig,
   SystemClock,
   UuidIdFactory,
@@ -50,6 +58,7 @@ import { makeCfRuntime } from './cf-runtime.js';
 import type { CfConnectionHandlers } from './cf-runtime.js';
 import type { Env } from './env.js';
 import { PERSISTED_STATE_VERSION, STATE_STORAGE_KEY, deserialize, serialize } from './serialize.js';
+import type { PersistedConnectionState } from './serialize.js';
 
 /** Default PING cadence (ms) — tuned for typical IRC client behavior. */
 export const DEFAULT_PING_INTERVAL_MS = 60_000;
@@ -90,6 +99,22 @@ export class ConnectionDO extends DurableObject<Env> {
    * should seed `createdAt` with its receive time.
    */
   private channelAccess: PassthroughChannelAccess | undefined;
+  /**
+   * Per-connection chat-history store backing `draft/chathistory`
+   * playback. The minimum-viable in-worker ring buffer is scoped to this
+   * connection: messages this connection sends are recorded and replayable
+   * by the same connection. A Durable-Object-backed persistent variant
+   * (shared across connections, keyed by channel) is a documented
+   * follow-up. Lazily constructed so the first frame seeds it.
+   */
+  private messages: MessageStore | undefined;
+  /**
+   * In-worker SASL account store seeded from the `SASL_ACCOUNTS` env var.
+   * Lazily constructed so the first frame that needs it parses the env once.
+   * A Durable-Object / D1-backed persistent variant is a documented
+   * follow-up; swapping it in means replacing {@link accountStore}.
+   */
+  private accounts: AccountStore | undefined;
   private readonly clock: Clock = SystemClock;
   private readonly ids: IdFactory = new UuidIdFactory();
   private readonly pingIntervalMs: number = DEFAULT_PING_INTERVAL_MS;
@@ -293,6 +318,11 @@ export class ConnectionDO extends DurableObject<Env> {
     if (this.channelAccess === undefined) {
       this.channelAccess = new PassthroughChannelAccess(this.clock.now(), this.env);
     }
+    // Workers Observability ingests `console.*` directly.
+    // Bound `connectionId` so every record the actor emits is filterable
+    // per-connection in the Workers dashboard.
+    const logger: Logger = new ConsoleLogger({ connectionId: state.id }, undefined, LogLevel.Info);
+    const accounts = this.accountStore();
     return new ConnectionActor({
       state,
       runtime,
@@ -301,6 +331,9 @@ export class ConnectionDO extends DurableObject<Env> {
       clock: this.clock,
       ids: this.ids,
       motd,
+      messages: this.messageStore(),
+      ...(accounts !== undefined ? { accounts } : {}),
+      logger,
     });
   }
 
@@ -351,6 +384,34 @@ export class ConnectionDO extends DurableObject<Env> {
     return { lines: () => raw.split('\n') };
   }
 
+  /**
+   * Lazily constructs the per-connection chat-history store. The ring
+   * buffer default cap matches the shared `InMemoryMessageStore`; a
+   * future persistent variant (DO/KV-backed, keyed by channel) will
+   * replace this without touching the actor wiring.
+   */
+  private messageStore(): MessageStore {
+    if (this.messages === undefined) {
+      this.messages = new InMemoryMessageStore();
+    }
+    return this.messages;
+  }
+
+  /**
+   * Lazily constructs the in-worker SASL account store from the
+   * `SASL_ACCOUNTS` env var. Returns `undefined` when no accounts are
+   * configured so the actor's `ctx.accounts` stays unset (preserving the
+   * no-store behaviour: `AUTHENTICATE PLAIN` → `904`). A Durable-Object /
+   * D1-backed persistent variant is a documented follow-up.
+   */
+  private accountStore(): AccountStore | undefined {
+    if (this.accounts !== undefined) return this.accounts;
+    const creds = parseSaslAccountsEnv(this.env.SASL_ACCOUNTS);
+    if (creds.length === 0) return undefined;
+    this.accounts = new InMemoryAccountStore(creds);
+    return this.accounts;
+  }
+
   // -------------------------------------------------------------------------
   // Test hooks (only invoked from `runInDurableObject` in tests)
   // -------------------------------------------------------------------------
@@ -394,6 +455,7 @@ export class ConnectionDO extends DurableObject<Env> {
       clock: this.clock,
       ids: this.ids,
       motd: this.motdProvider(),
+      messages: this.messageStore(),
     });
     await actor.receiveTextFrame('QUIT\r\n');
     await this.releaseAndPersist(state);
@@ -436,6 +498,38 @@ export class ConnectionDO extends DurableObject<Env> {
     const state = await this.loadState();
     return toSnapshot(state);
   }
+
+  /**
+   * Cross-connection RPC: returns the full connection state as a
+   * JSON-friendly DTO ({@link PersistedConnectionState}). Called by
+   * another connection's {@link CfRuntime} when a `GetConnection`
+   * lookup targets this connection (e.g. WHOIS). The DTO survives DO
+   * RPC because `Set`/`Map` fields are pre-flattened to arrays by
+   * {@link serialize}; the caller rehydrates via {@link deserialize}.
+   */
+  public async getConnState(): Promise<PersistedConnectionState | null> {
+    const state = await this.loadState();
+    return serialize(state);
+  }
+
+  /**
+   * Cross-connection RPC: tears down this connection. Reuses the same
+   * QUIT fan-out / nick-release / WebSocket-close path as the normal
+   * `webSocketClose` handler so KICK and operator-driven disconnect
+   * produce identical side effects. If no live socket is attached the
+   * no-socket teardown path still releases the nick.
+   */
+  public async disconnect(reason?: string): Promise<void> {
+    void reason;
+    const sockets = this.ctx.getWebSockets();
+    const ws = sockets[0];
+    if (ws === undefined) {
+      const state = await this.loadState();
+      await this.tearDownNoSocket(state);
+      return;
+    }
+    await this.tearDown(ws as WebSocket);
+  }
 }
 
 /** Default MOTD when no `MOTD_LINES` env is supplied. */
@@ -540,3 +634,28 @@ class PassthroughChannelAccess {
 // in production today. (Removed from the ConnectionDO path because the
 // authoritative delta application lives in the ChannelDO stub today.)
 export { applyChannelDelta, PERSISTED_STATE_VERSION };
+
+/**
+ * Parses the `SASL_ACCOUNTS` env var into credential entries.
+ *
+ * Format: newline-delimited `username:password` pairs (mirroring the
+ * `MOTD_LINES` convention). Blank lines and malformed entries (missing
+ * colon or empty username/password) are skipped so a trailing newline or a
+ * partial edit does not break boot. Exported so the parsing boundary is
+ * unit-testable in isolation.
+ */
+export function parseSaslAccountsEnv(raw: string | undefined): SaslAccountCredential[] {
+  if (raw === undefined || raw.length === 0) return [];
+  const out: SaslAccountCredential[] = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue; // missing colon or empty username
+    const username = trimmed.slice(0, sep);
+    const password = trimmed.slice(sep + 1);
+    if (username.length === 0 || password.length === 0) continue;
+    out.push({ username, password });
+  }
+  return out;
+}

package/packages/cf-adapter/src/env.ts

@@ -31,13 +31,28 @@ export interface Env {
   REGISTRY_DO: DurableObjectNamespace;
   /**
    * Channel authority, keyed by lowercased channel name. RPC: broadcast /
-   * applyChannelDelta / getChannelSnapshot. Stubbed now; real in 035.
+   * applyChannelDelta / getChannelSnapshot / listMembers. Stubbed now;
+   * real in 035.
    */
   CHANNEL_DO: DurableObjectNamespace;
+  /**
+   * Channel registry authority. A single DO instance tracks the set of
+   * all channel names so {@link CfRuntime.listChannels} can enumerate
+   * them without scanning every per-channel DO. RPC: register /
+   * unregister / list.
+   */
+  CHANNEL_REGISTRY_DO: DurableObjectNamespace;
   /** Server-level config knobs (name, MOTD lines, limits). */
   SERVER_NAME: string;
   NETWORK_NAME: string;
   MOTD_LINES: string;
+  /**
+   * 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. Empty/undefined disables SASL account verification.
+   */
+  SASL_ACCOUNTS?: string;
 }
 
 /**
@@ -64,4 +79,15 @@ export interface ChannelRpc {
   broadcast(lines: unknown[], except?: string): Promise<void>;
   applyChannelDelta(delta: unknown): Promise<void>;
   getChannelSnapshot(): Promise<unknown>;
+  listMembers(): Promise<string[]>;
+}
+
+/**
+ * RPC contract for the channel registry DO. Tracks the set of all
+ * channel names so {@link CfRuntime.listChannels} can enumerate them.
+ */
+export interface ChannelRegistryRpc {
+  register(name: string): Promise<void>;
+  unregister(name: string): Promise<void>;
+  list(): Promise<string[]>;
 }

package/packages/cf-adapter/src/index.ts

@@ -19,6 +19,7 @@ export {
 } from './connection-do.js';
 export { RegistryDO } from './registry-do.js';
 export { ChannelDO } from './channel-do.js';
+export { ChannelRegistryDO } from './channel-registry-do.js';
 export type { DeliverResult, ConnectionDeliveryRpc } from './channel-do.js';
 export {
   DEFAULT_REGISTRY_SHARDS,
@@ -27,7 +28,7 @@ export {
 } from './sharding.js';
 export { makeCfRuntime } from './cf-runtime.js';
 export type { CfConnectionHandlers } from './cf-runtime.js';
-export type { ChannelRpc, Env, RegistryRpc } from './env.js';
+export type { ChannelRpc, ChannelRegistryRpc, Env, RegistryRpc } from './env.js';
 export {
   PERSISTED_STATE_VERSION,
   STATE_STORAGE_KEY,

package/packages/cf-adapter/tests/cf-harness.ts

@@ -20,7 +20,7 @@ import type {
   IrcHarness,
   IrcHarnessFactory,
   SpawnClientOptions,
-} from './integration/harness.js';
+} from '@serverless-ircd/irc-test-support';
 
 /** Default tick for the polling waitFor* implementations (ms). */
 const POLL_MS = 10;
@@ -57,7 +57,7 @@ export interface CfHarnessEnv {
  *
  * ```ts
  * import { env } from 'cloudflare:test';
- * import { runIrcScenarios } from './integration/scenarios.js';
+ * import { runIrcScenarios } from '@serverless-ircd/irc-test-support';
  * import { makeCfHarnessFactory } from './cf-harness';
  *
  * runIrcScenarios([makeCfHarnessFactory({ env })]);

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

@@ -1,7 +1,7 @@
 /**
  * Parametrized IRC scenarios against the Cloudflare runtime — 036.
  *
- * Reuses the scenario runner from `./integration/scenarios.js`
+ * Reuses the scenario runner from `@serverless-ircd/irc-test-support`
  * (032) and registers the CF harness factory built on top of the
  * real ConnectionDO / RegistryDO / ChannelDO worker bindings. Each
  * scenario spawns one or more real WebSockets and drives the full
@@ -26,9 +26,9 @@
  */
 
 import { env, reset } from 'cloudflare:test';
+import { runIrcScenarios } from '@serverless-ircd/irc-test-support';
 import { afterAll, afterEach, beforeAll } from 'vitest';
 import { makeCfHarnessFactory } from './cf-harness';
-import { runIrcScenarios } from './integration/scenarios.js';
 
 declare global {
   namespace Cloudflare {

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

@@ -44,6 +44,7 @@ declare global {
       CHANNEL_DO: DurableObjectNamespace;
       CHANNEL_DO_REAL: DurableObjectNamespace;
       CHANNEL_DO_STUB: DurableObjectNamespace;
+      CHANNEL_REGISTRY_DO: DurableObjectNamespace;
     }
   }
 }
@@ -62,6 +63,7 @@ function envWithRealDOs(): Env {
     CONNECTION_DO: env.CONNECTION_DO,
     REGISTRY_DO: env.REGISTRY_DO_REAL,
     CHANNEL_DO: env.CHANNEL_DO_REAL,
+    CHANNEL_REGISTRY_DO: env.CHANNEL_REGISTRY_DO,
     SERVER_NAME: 'irc.example.com',
     NETWORK_NAME: 'ExampleNet',
     MOTD_LINES: '',
@@ -78,6 +80,7 @@ function envWithChannelStub(): Env {
     CONNECTION_DO: env.CONNECTION_DO,
     REGISTRY_DO: env.REGISTRY_DO_REAL,
     CHANNEL_DO: env.CHANNEL_DO_STUB,
+    CHANNEL_REGISTRY_DO: env.CHANNEL_REGISTRY_DO,
     SERVER_NAME: 'irc.example.com',
     NETWORK_NAME: 'ExampleNet',
     MOTD_LINES: '',
@@ -484,6 +487,94 @@ describe('CfRuntime — cross-connection RPC via ConnectionDO', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Tests — cross-connection getConnection / getChannelConnections / listChannels / disconnect
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — cross-connection lookups and disconnect', () => {
+  it('getConnection(remoteConnId) returns the remote connection state via RPC', async () => {
+    const targetName = 'conn-get-target';
+    const ws = await openConnection(targetName);
+    await new Promise<void>((r) => setTimeout(r, 20));
+    ws.send('NICK carol\r\n');
+    ws.send('USER carol 0 * :Carol\r\n');
+    await new Promise<void>((r) => setTimeout(r, 100));
+
+    const targetHexId = await getConnectionHexId(targetName);
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-get-caller', recordingHandlers());
+    const conn = await rt.getConnection(targetHexId);
+    expect(conn).not.toBeNull();
+    expect(conn?.nick).toBe('carol');
+    expect(conn?.id).toBe(targetHexId);
+
+    ws.close();
+  });
+
+  it('getChannelConnections(chan) returns the ConnectionStates of all members', async () => {
+    const memberName = 'conn-who-target';
+    const ws = await openConnection(memberName);
+    await new Promise<void>((r) => setTimeout(r, 20));
+    ws.send('NICK dave\r\n');
+    ws.send('USER dave 0 * :Dave\r\n');
+    await new Promise<void>((r) => setTimeout(r, 100));
+
+    const memberHexId = await getConnectionHexId(memberName);
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-who-caller', recordingHandlers());
+
+    await rt.applyChannelDelta('#whochan', {
+      memberships: [{ type: 'add' as const, conn: memberHexId, nick: 'dave' }],
+    });
+
+    const conns = await rt.getChannelConnections('#whochan');
+    expect(conns.size).toBe(1);
+    expect(conns.get(memberHexId)?.nick).toBe('dave');
+
+    ws.close();
+  });
+
+  it('listChannels returns channels registered in the registry', async () => {
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-list', recordingHandlers());
+
+    await rt.applyChannelDelta('#listchan', {
+      memberships: [{ type: 'add' as const, conn: 'conn-list', nick: 'eve' }],
+    });
+
+    const channels = await rt.listChannels();
+    expect(channels.length).toBeGreaterThan(0);
+    expect(channels.some((c) => c.nameLower === '#listchan')).toBe(true);
+  });
+
+  it('listChannels returns empty array when no channels exist', async () => {
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-list-empty', recordingHandlers());
+    const channels = await rt.listChannels();
+    expect(channels).toEqual([]);
+  });
+
+  it('disconnect(remoteConn) closes the target connection', async () => {
+    const targetName = 'conn-disc-target';
+    const ws = await openConnection(targetName);
+    await new Promise<void>((r) => setTimeout(r, 20));
+
+    const targetHexId = await getConnectionHexId(targetName);
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-disc-caller', recordingHandlers());
+
+    const closed = new Promise<void>((resolve) => {
+      ws.addEventListener('close', () => resolve());
+      setTimeout(resolve, 2000);
+    });
+
+    await rt.disconnect(targetHexId, 'Kicked');
+    await closed;
+
+    expect([WebSocket.CLOSING, WebSocket.CLOSED]).toContain(ws.readyState);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Tests — implements IrcRuntime
 // ---------------------------------------------------------------------------