serverless-ircd 0.3.0 → 0.4.0

package/packages/aws-adapter/src/handlers/nlb-stream.ts

@@ -0,0 +1,481 @@
+/**
+ * NLB TCP+TLS Lambda streaming handler.
+ *
+ * AWS Network Load Balancer with a `tls` listener terminates TLS at the edge
+ * and invokes a Lambda function as the target for each chunk of client data.
+ * The Lambda response body is streamed back to the client over the same TCP
+ * connection the NLB holds open.
+ *
+ * Connection identity: NLB does not hand out a stable connection id the way
+ * API Gateway does. The flow is identified by the 4-tuple
+ * (source-IP, source-port), exposed as `x-forwarded-for` /
+ * `x-forwarded-port` headers. {@link deriveNlbConnectionId} maps that tuple
+ * to the existing `connectionId` scheme (`nlb-<ip>-<port>`) so the same
+ * DynamoDB-backed state path serves both the wss and TCP+TLS transports.
+ *
+ * Transport buffer persistence: the `TcpByteStreamTransport` buffers
+ * partial lines (a chunk may split an IRC command at an arbitrary byte
+ * boundary). Because each chunk arrives in a fresh Lambda invocation, the
+ * buffered tail is snapshotted to a `transportBuffer` attribute on the
+ * Connections row and rehydrated on the next invocation — no bytes are lost
+ * across the compute boundary.
+ *
+ * Outbound bytes: self-send lines (PONG, welcome block, error numerics, …)
+ * are collected and returned as the Lambda response body (base64-encoded so
+ * binary-safe). Cross-connection fanout (PRIVMSG broadcast, QUIT fanout, …)
+ * flows through the bound `managementApi` exactly as the wss path does —
+ * when the deploy also exposes an APIGW management endpoint the two
+ * transports share one fanout backend; when `managementApi` is `null` the
+ * AwsRuntime silently no-ops cross-connection sends (documented platform
+ * limit, see `docs/AWS-Deployment.md`).
+ *
+ * NLB + Lambda streaming limits:
+ *   - Idle timeout: the NLB idle timeout (10–350 s) governs how long a
+ *     connection with no client data stays open. The sweeper + ping-checker
+ *     keep the DynamoDB row fresh and eventually prune it via `idleSince` TTL.
+ *   - No server-push: the Lambda can only respond to a client chunk; it
+ *     cannot proactively push bytes. Real-time fanout piggybacks on the
+ *     recipient's next chunk (response) or via the APIGW management API.
+ *   - Max connection duration: NLB has no hard max for TCP, but the
+ *     underlying flow may be rebalanced by the NLB at any time.
+ */
+
+import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
+import { GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import {
+  type AccountStore,
+  type ChannelState,
+  type Clock,
+  type ConnectionState,
+  type IdFactory,
+  type MessageStore,
+  type MotdProvider,
+  type NickHistoryStore,
+  type ParsedServerConfig,
+  SystemClock,
+  UuidIdFactory,
+} from '@serverless-ircd/irc-core';
+import {
+  type ActorChannelAccess,
+  ConnectionActor,
+  WsTextFrameTransport,
+} from '@serverless-ircd/irc-server';
+import { TcpByteStreamTransport } from '@serverless-ircd/irc-server';
+import { AwsRuntime, type AwsRuntimeHandlers, type PostToConnection } from '../aws-runtime.js';
+import type { MarshalledConnection } from '../serialize.js';
+import { CONNECTION_VERSION } from '../serialize.js';
+import type { TablesConfig } from '../tables.js';
+import { createInitialConnectionState } from './state.js';
+
+// ---------------------------------------------------------------------------
+// Event / response shapes
+// ---------------------------------------------------------------------------
+
+/**
+ * NLB Lambda target event (version 2.0). The `body` carries the client's
+ * raw TCP bytes, base64-encoded. Connection-identifying metadata is in
+ * the `headers` (`x-forwarded-for`, `x-forwarded-port`).
+ */
+export interface NlbStreamEvent {
+  requestContext: {
+    elb: {
+      targetGroupArn: string;
+    };
+  };
+  version: string;
+  body: string;
+  isBase64Encoded: boolean;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Lambda response consumed by the NLB. The `body` (base64-encoded) is the
+ * raw bytes the NLB forwards to the client over the held-open TCP socket.
+ */
+export interface NlbStreamResponse {
+  statusCode: number;
+  body: string;
+  isBase64Encoded: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Connection identity
+// ---------------------------------------------------------------------------
+
+/**
+ * Prefix distinguishing NLB-derived connection ids from APIGW ids in
+ * DynamoDB (so a client on both transports cannot collide).
+ */
+const NLB_CONN_PREFIX = 'nlb-';
+
+/**
+ * Derives a stable connection id from the NLB flow metadata (source IP +
+ * source port). Dots and colons in the IP are replaced with dashes so the
+ * id is safe for DynamoDB partition keys and logging.
+ *
+ * The NLB holds the TCP connection open for the lifetime of the flow, so
+ * the same `(ip, port)` pair maps to the same connection across every
+ * Lambda invocation for that flow.
+ */
+export function deriveNlbConnectionId(sourceIp: string, sourcePort: string): string {
+  const safeIp = sourceIp.replace(/[.:]/g, '-');
+  return `${NLB_CONN_PREFIX}${safeIp}-${sourcePort}`;
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+/** Parameters accepted by {@link handleNlbStream}. */
+export interface NlbStreamParams {
+  dynamo: DynamoDBDocumentClient;
+  tables: TablesConfig;
+  serverConfig: ParsedServerConfig;
+  motd: MotdProvider;
+  /** Chat-history persistence source (same as the wss `$default` path). */
+  messages?: MessageStore;
+  /** SASL account verification source. */
+  accounts?: AccountStore;
+  /** mTLS identity source for SASL EXTERNAL. */
+  mtlsIdentity?: import('@serverless-ircd/irc-core').MtlsIdentityProvider;
+  /** Nick-history source for WHOWAS. */
+  history?: NickHistoryStore;
+  /**
+   * Backend for cross-connection fanout. `null` when the deploy is NLB-only
+   * (no APIGW management endpoint) — cross-connection sends are silent
+   * no-ops in that mode.
+   */
+  managementApi: ApiGatewayManagementApi | PostToConnection | null;
+  /** Injected for tests; defaults to {@link SystemClock}. */
+  clock?: Clock;
+  /** Injected for tests; defaults to {@link UuidIdFactory}. */
+  ids?: IdFactory;
+}
+
+/**
+ * Processes one NLB chunk: decodes the client bytes, frames them through
+ * the persistent TCP transport buffer, runs complete lines through the
+ * actor, persists state + buffer, and returns the outbound bytes for the
+ * NLB to stream back to the client.
+ *
+ * On the first chunk for a flow (no Connections row), a fresh row is
+ * created before processing — there is no separate `$connect` event from
+ * the NLB.
+ */
+export async function handleNlbStream(
+  event: NlbStreamEvent,
+  params: NlbStreamParams,
+): Promise<NlbStreamResponse> {
+  const clock = params.clock ?? SystemClock;
+  const ids = params.ids ?? new UuidIdFactory();
+  const now = clock.now();
+
+  // 1. Decode the client bytes.
+  const data = event.isBase64Encoded
+    ? Buffer.from(event.body, 'base64').toString('utf8')
+    : event.body;
+
+  // 2. Derive the connection id from NLB flow metadata.
+  const sourceIp = readHeader(event, 'x-forwarded-for') ?? 'unknown';
+  const sourcePort = readHeader(event, 'x-forwarded-port') ?? '0';
+  const connId = deriveNlbConnectionId(sourceIp, sourcePort);
+
+  // 3. Load the existing row (if any) and split the transport buffer.
+  const existing = await loadRow(params.dynamo, params.tables.Connections, connId);
+  let state: ConnectionState;
+  let transportBuffer: string;
+  if (existing === null) {
+    state = createInitialConnectionState(connId, now);
+    if (sourceIp !== 'unknown') state.host = sourceIp;
+    transportBuffer = '';
+  } else {
+    state = unmarshalState(existing);
+    transportBuffer = typeof existing.transportBuffer === 'string' ? existing.transportBuffer : '';
+  }
+
+  // 4. Frame the chunk through the persistent TCP transport.
+  const transport = new TcpByteStreamTransport();
+  transport.restore(transportBuffer);
+  const lines = transport.feed(data);
+  const newBuffer = transport.getBuffer();
+
+  // Mark activity.
+  state.lastSeen = now;
+
+  // 5. Run complete lines through the actor (if any).
+  const outbound: string[] = [];
+  const handlers: AwsRuntimeHandlers = {
+    send: (sentLines) => {
+      for (const l of sentLines) outbound.push(l.text);
+    },
+    disconnect: () => {
+      // The Lambda cannot force-close the NLB-held TCP socket from inside
+      // the invocation. The canonical teardown is the sweeper + idleSince
+      // TTL (same pattern as the APIGW `$default` path, which also cannot
+      // close its own socket — see docs/AWS-Deployment.md §14.1).
+    },
+    snapshot: () => state,
+  };
+
+  const runtime = new AwsRuntime({
+    dynamo: params.dynamo,
+    tables: params.tables,
+    connId,
+    handlers,
+    managementApi: params.managementApi,
+    clock,
+  });
+
+  const channelAccess = new NlbChannelAccess(runtime, now);
+
+  const actor = new ConnectionActor({
+    state,
+    runtime,
+    channels: channelAccess,
+    serverConfig: params.serverConfig,
+    clock,
+    ids,
+    motd: params.motd,
+    // The actor receives already-framed complete lines; a stateless
+    // WsTextFrameTransport splits on \r\n (no-op for already-split lines).
+    transport: new WsTextFrameTransport(),
+    ...(params.messages !== undefined ? { messages: params.messages } : {}),
+    ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
+    ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
+    ...(params.history !== undefined ? { history: params.history } : {}),
+  });
+
+  if (lines.length > 0) {
+    try {
+      await actor.receiveTextFrame(lines.join('\r\n'));
+    } catch (err: unknown) {
+      console.error('[nlb-stream] actor.receiveTextFrame failed', err);
+    }
+  }
+
+  // 6. Persist state + transport buffer.
+  await persistStateAndBuffer(
+    params.dynamo,
+    params.tables.Connections,
+    connId,
+    state,
+    now,
+    newBuffer,
+  );
+
+  // 7. Return outbound bytes as the NLB response body.
+  const responseBody = outbound.length > 0 ? `${outbound.join('\r\n')}\r\n` : '';
+  return {
+    statusCode: 200,
+    body: Buffer.from(responseBody, 'utf8').toString('base64'),
+    isBase64Encoded: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal — DynamoDB helpers
+// ---------------------------------------------------------------------------
+
+/** Raw row shape (extends the marshalled connection with the transport buffer). */
+type RawConnectionRow = MarshalledConnection & { transportBuffer?: string };
+
+/** Reads a header case-insensitively (NLB lowercases header names). */
+function readHeader(event: NlbStreamEvent, name: string): string | undefined {
+  const headers = event.headers;
+  if (headers === undefined) return undefined;
+  const lower = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === lower) return value;
+  }
+  return undefined;
+}
+
+/** Loads a raw Connections row (includes transportBuffer if present). */
+async function loadRow(
+  dynamo: DynamoDBDocumentClient,
+  tableName: string,
+  connId: string,
+): Promise<RawConnectionRow | null> {
+  const result = await dynamo.send(
+    new GetCommand({ TableName: tableName, Key: { connectionId: connId } }),
+  );
+  if (result.Item === undefined) return null;
+  return result.Item as unknown as RawConnectionRow;
+}
+
+/** Unmarshals a raw row into a ConnectionState (ignores transportBuffer). */
+function unmarshalState(row: RawConnectionRow): ConnectionState {
+  // Strip transportBuffer before unmarshalling so it is not treated as a
+  // stray ConnectionState field.
+  const { transportBuffer: _drop, ...connFields } = row;
+  void _drop;
+  return unmarshalConnectionTyped(connFields);
+}
+
+/**
+ * Thin wrapper around `unmarshalConnection` that accepts the stripped row.
+ * Importing lazily keeps the module boundary clean.
+ */
+import { unmarshalConnection } from '../serialize.js';
+function unmarshalConnectionTyped(row: MarshalledConnection): ConnectionState {
+  return unmarshalConnection(row);
+}
+
+/**
+ * Persists the mutated state and the new transport buffer in a single
+ * UpdateCommand. The buffer is written as a plain string attribute — when
+ * empty it is REMOVE'd so stale buffers from a previous chunk do not
+ * linger after the line completes.
+ */
+async function persistStateAndBuffer(
+  dynamo: DynamoDBDocumentClient,
+  tableName: string,
+  connId: string,
+  state: ConnectionState,
+  now: number,
+  transportBuffer: string,
+): Promise<void> {
+  // Build the standard persist expression (same fields as handleDefault's
+  // buildPersistUpdate, minus the joinedChannels which the membership
+  // transaction owns).
+  const values: Record<string, unknown> = {
+    ':reg': state.registration,
+    ':capN': state.capNegotiating,
+    ':caps': [...state.caps],
+    ':um': { ...state.userModes },
+    ':ls': state.lastSeen,
+    ':is': now,
+    ':v': CONNECTION_VERSION,
+  };
+  const setNames = [
+    'registration = :reg',
+    'capNegotiating = :capN',
+    'caps = :caps',
+    'userModes = :um',
+    'lastSeen = :ls',
+    'idleSince = :is',
+    'version = :v',
+  ];
+  const removeNames: string[] = [];
+  const nameMap: Record<string, string> = {};
+
+  for (const field of OPTIONAL_CONN_FIELDS) {
+    const placeholder = `:${field}`;
+    const value = state[field] as string | undefined;
+    const nameKey = `#${field}`;
+    nameMap[nameKey] = field;
+    if (value !== undefined) {
+      values[placeholder] = value;
+      setNames.push(`${nameKey} = ${placeholder}`);
+    } else {
+      removeNames.push(nameKey);
+    }
+  }
+
+  // Transport buffer: SET when non-empty, REMOVE when empty.
+  nameMap['#tb'] = 'transportBuffer';
+  if (transportBuffer.length > 0) {
+    values[':tb'] = transportBuffer;
+    setNames.push('#tb = :tb');
+  } else {
+    removeNames.push('#tb');
+  }
+
+  const parts: string[] = [`SET ${setNames.join(', ')}`];
+  if (removeNames.length > 0) {
+    parts.push(`REMOVE ${removeNames.join(', ')}`);
+  }
+
+  await dynamo.send(
+    new UpdateCommand({
+      TableName: tableName,
+      Key: { connectionId: connId },
+      UpdateExpression: parts.join(' '),
+      ExpressionAttributeValues: values,
+      ExpressionAttributeNames: nameMap,
+    }),
+  );
+}
+
+/** Optional connection fields mirrored into the SET/REMOVE split. */
+const OPTIONAL_CONN_FIELDS = [
+  'nick',
+  'user',
+  'host',
+  'realname',
+  'passAttempt',
+  'account',
+  'away',
+  'saslMech',
+  'saslBuffer',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Channel access (mirrors LambdaChannelAccess from default.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * `ActorChannelAccess` backed by the per-invocation {@link AwsRuntime}.
+ * Identical to `LambdaChannelAccess` in `default.ts` — duplicated rather
+ * than shared so the NLB handler stays self-contained (no cross-handler
+ * import coupling).
+ */
+class NlbChannelAccess implements ActorChannelAccess {
+  private readonly cache = new Map<string, ChannelState>();
+  constructor(
+    private readonly runtime: AwsRuntime,
+    private readonly now: number,
+  ) {}
+
+  getOrCreateChannel(name: string): ChannelState {
+    const key = name.toLowerCase();
+    const existing = this.cache.get(key);
+    if (existing !== undefined) return existing;
+    const created: ChannelState = {
+      name,
+      nameLower: key,
+      modes: {
+        inviteOnly: false,
+        topicLock: false,
+        noExternal: false,
+        moderated: false,
+        secret: false,
+        private: false,
+      },
+      banMasks: new Set<string>(),
+      members: new Map(),
+      pendingInvites: new Set<string>(),
+      createdAt: this.now,
+    };
+    this.cache.set(key, created);
+    return created;
+  }
+
+  async refreshChannel(name: string): Promise<void> {
+    const key = name.toLowerCase();
+    const snap = await this.runtime.getChannelSnapshot(name);
+    if (snap === null) return;
+    const existing = this.cache.get(key);
+    if (snap.members.size === 0) {
+      if (existing !== undefined) {
+        existing.modes = { ...snap.modes };
+        existing.banMasks = new Set(snap.banMasks);
+        existing.pendingInvites = new Set(snap.pendingInvites);
+        if (snap.topic !== undefined) existing.topic = snap.topic;
+      }
+      return;
+    }
+    const rebuilt: ChannelState = {
+      name,
+      nameLower: key,
+      modes: { ...snap.modes },
+      banMasks: new Set(snap.banMasks),
+      members: new Map(snap.members),
+      pendingInvites: new Set(snap.pendingInvites),
+      createdAt: snap.createdAt,
+    };
+    if (snap.topic !== undefined) rebuilt.topic = snap.topic;
+    this.cache.set(key, rebuilt);
+  }
+}

package/packages/aws-adapter/src/handlers/ping-checker.ts

@@ -187,7 +187,7 @@ export async function handlePingCheck(params: PingCheckParams): Promise<PingChec
 // Internals
 // ---------------------------------------------------------------------------
 
-/** Default token source — Node 20 Lambda runtime exposes `crypto.randomUUID` globally. */
+/** Default token source — Node 24 Lambda runtime exposes `crypto.randomUUID` globally. */
 function defaultToken(): string {
   return randomUUID();
 }

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

@@ -51,6 +51,9 @@ export {
   handler,
   dispatch,
   buildDepsFromEnv,
+  nlbStreamHandler,
+  handleNlbStream,
+  deriveNlbConnectionId,
   pingCheckerHandler,
   sweeperHandler,
   handlePingCheck,
@@ -66,6 +69,9 @@ export type {
   DisconnectEvent,
   HandlerDeps,
   LambdaResponse,
+  NlbStreamEvent,
+  NlbStreamParams,
+  NlbStreamResponse,
   PingCheckParams,
   PingCheckResult,
   SweepParams,

package/packages/aws-adapter/tests/account-store-dynamo.test.ts

@@ -31,6 +31,11 @@ interface Fx {
 
 let fx: Fx | null = null;
 
+function requireFx(): Fx {
+  if (!fx) throw new Error('test fixture not initialized');
+  return fx;
+}
+
 async function makeFx(): Promise<Fx> {
   if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
   const tableName = `acct-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
@@ -69,55 +74,57 @@ describe.skipIf(!available)('Accounts table round-trip', () => {
   });
 
   it('putAccountCredential then loadDynamoAccountStore verifies the account', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 's3cret');
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 's3cret');
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeDefined();
-    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 's3cret' })).toEqual(
-      {
-        ok: true,
-        account: 'alice',
-      },
-    );
+    expect(
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 's3cret' }),
+    ).toEqual({
+      ok: true,
+      account: 'alice',
+    });
   });
 
   it('loadDynamoAccountStore returns undefined when the table has no rows', async () => {
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeUndefined();
   });
 
   it('putAccountCredential writes multiple distinct accounts', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'a1');
-    await putAccountCredential(fx!.client, fx!.tableName, 'bob', 'b2');
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'a1');
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'bob', 'b2');
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeDefined();
-    expect(store!.size).toBe(2);
-    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'a1' }).ok).toBe(
+    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,
     );
-    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'bob', password: 'b2' }).ok).toBe(true);
   });
 
   it('putAccountCredential overwrites an existing account (re-seed)', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'old');
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'new');
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'old');
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'new');
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeDefined();
-    expect(store!.size).toBe(1);
-    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'old' }).ok).toBe(
+    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(
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'new' }).ok).toBe(
       true,
     );
   });
 
   it('rejects a wrong password after round-trip', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'right');
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'right');
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeDefined();
-    expect(
-      store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'wrong' }).ok,
-    ).toBe(false);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'wrong' }).ok).toBe(
+      false,
+    );
   });
 });
 
@@ -131,19 +138,19 @@ describe.skipIf(!available)('resolveAccountStore precedence', () => {
   });
 
   it('returns a DynamoAccountStore when the table has rows (table wins)', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'table-secret');
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'table-secret');
     const cfgWithSasl = {
       ...DEFAULT_SERVER_CONFIG,
       saslAccounts: [{ username: 'envuser', password: 'env-secret' }],
     };
-    const store = await resolveAccountStore(fx!.client, fx!.tableName, cfgWithSasl);
+    const store = await resolveAccountStore(requireFx().client, requireFx().tableName, cfgWithSasl);
     expect(store).toBeDefined();
     // Table account verifies; config account does NOT (table is authoritative).
     expect(
-      store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'table-secret' }).ok,
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'table-secret' }).ok,
     ).toBe(true);
     expect(
-      store!.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
     ).toBe(false);
   });
 
@@ -152,20 +159,24 @@ describe.skipIf(!available)('resolveAccountStore precedence', () => {
       ...DEFAULT_SERVER_CONFIG,
       saslAccounts: [{ username: 'envuser', password: 'env-secret' }],
     };
-    const store = await resolveAccountStore(fx!.client, fx!.tableName, cfgWithSasl);
+    const store = await resolveAccountStore(requireFx().client, requireFx().tableName, cfgWithSasl);
     expect(store).toBeDefined();
     expect(
-      store!.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
     ).toBe(true);
   });
 
   it('returns undefined when the table is empty and no config accounts are set', async () => {
-    const store = await resolveAccountStore(fx!.client, fx!.tableName, DEFAULT_SERVER_CONFIG);
+    const store = await resolveAccountStore(
+      requireFx().client,
+      requireFx().tableName,
+      DEFAULT_SERVER_CONFIG,
+    );
     expect(store).toBeUndefined();
   });
 
   it('returns undefined when the table is empty and serverConfig is undefined', async () => {
-    const store = await resolveAccountStore(fx!.client, fx!.tableName, undefined);
+    const store = await resolveAccountStore(requireFx().client, requireFx().tableName, undefined);
     expect(store).toBeUndefined();
   });
 });