serverless-ircd 0.4.0 → 0.6.0

package/packages/aws-adapter/src/handlers/default.ts

@@ -22,9 +22,12 @@ import {
   type MtlsIdentityProvider,
   type NickHistoryStore,
   type ParsedServerConfig,
+  type ServerConfig,
   SystemClock,
   UuidIdFactory,
+  type WsFrameMode,
   createConnection,
+  frameToLines,
 } from '@serverless-ircd/irc-core';
 import { type ActorChannelAccess, ConnectionActor } from '@serverless-ircd/irc-server';
 import { AwsRuntime, type AwsRuntimeHandlers, type PostToConnection } from '../aws-runtime.js';
@@ -33,8 +36,18 @@ import {
   type MarshalledConnection,
   unmarshalConnection,
 } from '../serialize.js';
+import { AwsStats } from '../stats.js';
 import type { TablesConfig } from '../tables.js';
 
+/**
+ * Wall-clock timestamp captured at this Lambda isolate's first module load
+ * (cold start). Used as the `uptimeStartedAt` anchor for {@link AwsStats}
+ * so `STATS u` reports uptime for the current isolate. A deployment-wide
+ * uptime would require a persistent record (future work); for now each
+ * isolate reports its own.
+ */
+const LAMBDA_STARTUP_AT = Date.now();
+
 /** Parameters accepted by {@link handleDefault}. */
 export interface DefaultParams {
   dynamo: DynamoDBDocumentClient;
@@ -86,6 +99,12 @@ export interface DefaultParams {
   ids?: IdFactory;
   /** Optional management endpoint URL used when constructing a default client. */
   managementEndpoint?: string;
+  /**
+   * Config-reload source for `REHASH`. When omitted the runtime's
+   * `reloadConfig` rejects so the actor emits a graceful error-suffixed
+   * `382` and retains the prior config.
+   */
+  configLoader?: () => Promise<ServerConfig>;
 }
 
 /**
@@ -112,6 +131,12 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
   const persisted = result.Item as unknown as MarshalledConnection;
   const state = unmarshalConnection(persisted);
 
+  // Recover the IRCv3 WebSocket frame mode persisted at `$connect`.
+  // Absent = legacy (no subprotocol negotiated). Drives both the inbound
+  // line-framing transport (spec: one IRC message per frame, never split)
+  // and the outbound delivery shape (spec: one postToConnection per line).
+  const wsMode: WsFrameMode = persisted.wsMode ?? 'legacy';
+
   // Mark this frame's activity.
   state.lastSeen = clock.now();
 
@@ -141,6 +166,7 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
     handlers,
     managementApi: params.managementApi,
     clock,
+    ...(params.configLoader !== undefined ? { configLoader: params.configLoader } : {}),
   });
 
   const channelAccess = new LambdaChannelAccess(runtime, clock.now());
@@ -150,13 +176,27 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
     runtime,
     channels: channelAccess,
     serverConfig: params.serverConfig,
+    configSource: 'Secrets Manager',
     clock,
     ids,
     motd: params.motd,
+    transport: { feed: (chunk) => frameToLines(chunk, wsMode) },
+    // AwsStats Scans Connections + ChannelMeta for LUSERS/STATS.
+    // `uptimeStartedAt` is captured at the Lambda's cold start so `STATS u`
+    // reports per-isolate uptime; a deployment-wide uptime would require a
+    // persistent record (future work).
+    stats: new AwsStats({
+      dynamo: params.dynamo,
+      tables: params.tables,
+      uptimeStartedAt: LAMBDA_STARTUP_AT,
+    }),
     ...(params.messages !== undefined ? { messages: params.messages } : {}),
     ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
     ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
     ...(params.history !== undefined ? { history: params.history } : {}),
+    // API Gateway terminates TLS before the Lambda is invoked, so every
+    // WebSocket connection is secure → user mode `S`.
+    secure: true,
   });
 
   try {
@@ -172,13 +212,12 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
   await persistState(params.dynamo, params.tables, params.connectionId, state, clock.now());
 
   // In production, deliver outbound bytes back to the caller via APIGW.
+  // Spec-mode connections (text/binary.ircv3.net) receive exactly one IRC
+  // line per `postToConnection` (no trailing CRLF); legacy connections
+  // receive every line CRLF-joined in a single message.
   if (params.managementApi !== null && outbound.length > 0) {
-    const data = outbound.join('\r\n');
     try {
-      await params.managementApi.postToConnection({
-        ConnectionId: params.connectionId,
-        Data: data,
-      });
+      await postOutbound(params.managementApi, params.connectionId, outbound, wsMode);
     } catch {
       // The handler still returns 200 — the actor's mutations are
       // persisted; the caller just didn't see the reply this frame.
@@ -187,6 +226,28 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
   return { statusCode: 200 };
 }
 
+/**
+ * Delivers `lines` to `connectionId` via APIGW according to `mode`:
+ *   - `legacy` — all lines joined with `\r\n` in a single `postToConnection`.
+ *   - `spec-text` / `spec-binary` — one `postToConnection` per line, no
+ *     trailing CRLF (the IRCv3 WebSocket contract: one IRC message per
+ *     WebSocket message).
+ */
+async function postOutbound(
+  api: ApiGatewayManagementApi | PostToConnection,
+  connectionId: string,
+  lines: string[],
+  mode: WsFrameMode,
+): Promise<void> {
+  if (mode === 'legacy') {
+    await api.postToConnection({ ConnectionId: connectionId, Data: lines.join('\r\n') });
+    return;
+  }
+  for (const line of lines) {
+    await api.postToConnection({ ConnectionId: connectionId, Data: line });
+  }
+}
+
 /**
  * Writes the actor's mutated `state` back to the Connections row.
  *

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

@@ -21,6 +21,7 @@ import {
   type MotdProvider,
   type NickHistoryStore,
   type ParsedServerConfig,
+  type ServerConfig,
   StaticMotdProvider,
   SystemClock,
 } from '@serverless-ircd/irc-core';
@@ -68,6 +69,12 @@ export interface WebSocketEvent {
      */
     identity?: { sourceIp?: string };
   };
+  /**
+   * Request headers. APIGW populates `event.headers` on every route; the
+   * `$connect` upgrade carries the client's `Sec-WebSocket-Protocol` offer
+   * here so the handler can negotiate the IRCv3 subprotocol.
+   */
+  headers?: Record<string, string>;
   body?: string;
 }
 
@@ -75,6 +82,12 @@ export interface WebSocketEvent {
 export interface LambdaResponse {
   statusCode: number;
   body?: string;
+  /**
+   * Response headers. The `$connect` route sets `Sec-WebSocket-Protocol`
+   * to echo the agreed IRCv3 subprotocol back to the client; the CDK
+   * integration-response maps it onto the WebSocket handshake.
+   */
+  headers?: Record<string, string>;
 }
 
 /** Injectable dependencies. Tests construct one of these to bypass env loading. */
@@ -105,13 +118,24 @@ export interface HandlerDeps {
    * variant is a documented follow-up.
    */
   history?: NickHistoryStore;
+  /**
+   * Config-reload source for `REHASH` — re-invokes the Lambda env config
+   * loader (Secrets Manager / SSM / env vars). Bound once per cold start;
+   * each `REHASH` re-reads the live env so rotated oper creds / MOTD take
+   * effect without a redeploy. When omitted the actor's graceful failure
+   * path applies (error-suffixed `382`).
+   */
+  configLoader?: () => Promise<ServerConfig>;
 }
 
 /**
  * Strongly-typed event discriminated by routeKey. Useful for tests that
  * construct events directly.
  */
-export type ConnectEvent = { requestContext: { routeKey: '$connect'; connectionId: string } };
+export type ConnectEvent = {
+  requestContext: { routeKey: '$connect'; connectionId: string };
+  headers?: Record<string, string>;
+};
 export type DisconnectEvent = {
   requestContext: { routeKey: '$disconnect'; connectionId: string };
 };
@@ -162,8 +186,17 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
         tables: deps.tables,
         connectionId: connId,
         serverConfig: deps.serverConfig,
+        secWebSocketProtocol: event.headers?.['Sec-WebSocket-Protocol'] ?? null,
       });
-      if (outcome.admitted) return { statusCode: 200 };
+      if (outcome.admitted) {
+        if (outcome.subprotocol !== null) {
+          return {
+            statusCode: 200,
+            headers: { 'Sec-WebSocket-Protocol': outcome.subprotocol },
+          };
+        }
+        return { statusCode: 200 };
+      }
       return { statusCode: outcome.statusCode, body: outcome.reason };
     }
 
@@ -192,6 +225,7 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
           messages: deps.messages,
           ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
           ...(deps.history !== undefined ? { history: deps.history } : {}),
+          ...(deps.configLoader !== undefined ? { configLoader: deps.configLoader } : {}),
           managementApi: deps.managementApi,
         });
         return result;
@@ -333,6 +367,10 @@ export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Pr
   const messages = bindMessageStore(cfg);
   const history = new InMemoryNickHistoryStore(SystemClock);
   const accounts = await resolveAccountStore(dynamo, tables.Accounts, cfg);
+  // REHASH reload source: re-read the live env so a rotated oper password
+  // or MOTD takes effect on the next REHASH without a redeploy.
+  const configLoader = async (): Promise<ServerConfig> =>
+    loadServerConfigFromLambdaEnv(env as LambdaConfigEnv);
   return {
     dynamo,
     tables,
@@ -341,6 +379,7 @@ export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Pr
     managementApi,
     messages,
     history,
+    configLoader,
     ...(accounts !== undefined ? { accounts } : {}),
   };
 }

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

@@ -53,6 +53,7 @@ import {
   type MotdProvider,
   type NickHistoryStore,
   type ParsedServerConfig,
+  type ServerConfig,
   SystemClock,
   UuidIdFactory,
 } from '@serverless-ircd/irc-core';
@@ -151,6 +152,19 @@ export interface NlbStreamParams {
   clock?: Clock;
   /** Injected for tests; defaults to {@link UuidIdFactory}. */
   ids?: IdFactory;
+  /**
+   * Config-reload source for `REHASH` (same as the wss `$default` path).
+   * When omitted the runtime's `reloadConfig` rejects so the actor emits a
+   * graceful error-suffixed `382`.
+   */
+  configLoader?: () => Promise<ServerConfig>;
+  /**
+   * Whether the NLB listener terminates TLS for this flow. Set to `true`
+   * when the target group fronts a TLS listener (the `irc+tls://` port) so
+   * the connection surfaces user mode `S`; omit / set `false` for a plain
+   * TCP listener. The stack code sets this from the listener protocol.
+   */
+  secure?: boolean;
 }
 
 /**
@@ -225,6 +239,7 @@ export async function handleNlbStream(
     handlers,
     managementApi: params.managementApi,
     clock,
+    ...(params.configLoader !== undefined ? { configLoader: params.configLoader } : {}),
   });
 
   const channelAccess = new NlbChannelAccess(runtime, now);
@@ -234,6 +249,7 @@ export async function handleNlbStream(
     runtime,
     channels: channelAccess,
     serverConfig: params.serverConfig,
+    configSource: 'Secrets Manager',
     clock,
     ids,
     motd: params.motd,
@@ -244,6 +260,8 @@ export async function handleNlbStream(
     ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
     ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
     ...(params.history !== undefined ? { history: params.history } : {}),
+    // Surface TLS fact when the NLB listener terminates TLS (irc+tls port).
+    ...(params.secure === true ? { secure: true } : {}),
   });
 
   if (lines.length > 0) {

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

@@ -23,6 +23,8 @@ export {
   loadDynamoAccountStore,
 } from './dynamo-account-store.js';
 export { bindAccountStore, putAccountCredential, resolveAccountStore } from './account-store.js';
+export { AwsStats } from './stats.js';
+export type { AwsStatsOptions } from './stats.js';
 export {
   loadServerConfigFromLambdaEnv,
   type LambdaConfigEnv,

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

@@ -30,6 +30,7 @@ import type {
   RegistrationState,
   RosterEntry,
   UserModes,
+  WsFrameMode,
 } from '@serverless-ircd/irc-core';
 
 // ---------------------------------------------------------------------------
@@ -55,6 +56,13 @@ export interface MarshalledConnection {
   connectionId: ConnId;
   registration: RegistrationState;
   capNegotiating: boolean;
+  /**
+   * Transport TLS fact (user mode `S`). Optional on the persisted shape so
+   * rows written before the field shipped deserialize with a `false`
+   * default via the coalescing in {@link unmarshalConnection}. Always
+   * written by {@link marshalConnection}.
+   */
+  secure?: boolean;
   caps: string[];
   /**
    * Present (as a JS `Set`, auto-marshalled to `SS`) only when the
@@ -76,6 +84,15 @@ export interface MarshalledConnection {
   away?: string;
   saslMech?: string;
   saslBuffer?: string;
+  /**
+   * Negotiated IRCv3 WebSocket frame mode persisted at `$connect` time.
+   * Absent (`undefined`) on legacy connections (no subprotocol agreed) so
+   * the DynamoDB column is null by default — mirroring the CF adapter's
+   * hibernation-tag default. Set once and never mutated: `$default` uses
+   * `UpdateCommand` for its partial writes, so this field survives every
+   * subsequent frame.
+   */
+  wsMode?: WsFrameMode;
 }
 
 /**
@@ -92,6 +109,7 @@ export function marshalConnection(state: ConnectionState, idleSince: number): Ma
     connectionId: state.id,
     registration: state.registration,
     capNegotiating: state.capNegotiating,
+    secure: state.secure,
     caps: [...state.caps],
     userModes: { ...state.userModes },
     lastSeen: state.lastSeen,
@@ -118,7 +136,7 @@ export function marshalConnection(state: ConnectionState, idleSince: number): Ma
 /**
  * Materialises a {@link ConnectionState} from a stored row. Rehydrates
  * `caps` and `joinedChannels` into Sets. Throws on unrecognised
- * `version` values (forward migrations live in a future ticket).
+ * `version` values (forward migrations are not yet implemented).
  */
 export function unmarshalConnection(row: MarshalledConnection): ConnectionState {
   if (row.version > CONNECTION_VERSION) {
@@ -130,13 +148,20 @@ export function unmarshalConnection(row: MarshalledConnection): ConnectionState
     id: row.connectionId,
     registration: row.registration,
     capNegotiating: row.capNegotiating,
+    // `secure` is absent on rows persisted before user mode `S` shipped;
+    // default to false (plain transport) so the state shape stays satisfied.
+    secure: row.secure ?? false,
     caps: new Set<string>(row.caps),
     // `joinedChannels` is absent on rows that never joined a channel
     // (DynamoDB rejects empty sets); default to an empty Set. The SDK
     // unmarshalls `SS` back to a native Set, which the Set constructor
     // copies; arrays (older rows) also iterate fine.
     joinedChannels: new Set<ChanName>(row.joinedChannels ?? []),
-    userModes: { ...row.userModes },
+    // `userModes.tls` is absent on rows persisted before user mode `S`
+    // shipped; default to false so the field is a real boolean rather than
+    // `undefined`. Cast to Partial so TypeScript accepts the explicit
+    // default without flagging the spread overwrite (TS2783).
+    userModes: normalizeUserModes(row.userModes),
     lastSeen: row.lastSeen,
     connectedSince: row.connectedSince,
   };
@@ -152,6 +177,19 @@ export function unmarshalConnection(row: MarshalledConnection): ConnectionState
   return state;
 }
 
+/**
+ * Defaults `tls` to false on a deserialized `UserModes`. Rows persisted
+ * before user mode `S` shipped lack the field; the DynamoDB SDK round-trip
+ * yields `undefined`, which would leak into runtime code expecting a real
+ * boolean. Casting to `Partial` lets the explicit default apply without
+ * TypeScript flagging the spread overwrite (TS2783).
+ */
+function normalizeUserModes(um: UserModes): UserModes {
+  const out: Partial<UserModes> = { ...um };
+  if (out.tls === undefined) out.tls = false;
+  return out as UserModes;
+}
+
 // ---------------------------------------------------------------------------
 // Nicks
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,80 @@
+/**
+ * AWS-flavoured {@link ServerStats} backend.
+ *
+ * Aggregates the network-wide counts the `LUSERS` / `STATS` reducers need
+ * directly from DynamoDB: a single `Scan` over `Connections` (the source
+ * of truth for every live connection) and one over `ChannelMeta` (one row
+ * per channel). Classification (oper / invisible / unknown) is delegated
+ * to the shared {@link computeStatsSnapshot} helper in irc-core so the
+ * classification rules live in exactly one place.
+ *
+ * Constructed per `LUSERS` / `STATS` invocation alongside the
+ * {@link AwsRuntime}; cheap to build, no caching. `uptimeStartedAt` is
+ * supplied by the caller (typically the Lambda's cold-start timestamp,
+ * stashed in module scope at first import).
+ */
+
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { type ServerStatsSnapshot, computeStatsSnapshot } from '@serverless-ircd/irc-core';
+import type { MarshalledConnection } from './serialize.js';
+import { unmarshalConnection } from './serialize.js';
+import type { TablesConfig } from './tables.js';
+
+export interface AwsStatsOptions {
+  /** DynamoDB DocumentClient (the same client used by {@link AwsRuntime}). */
+  readonly dynamo: DynamoDBDocumentClient;
+  /** Logical→physical table-name map. */
+  readonly tables: TablesConfig;
+  /** Epoch-ms the deployment counts uptime from (Lambda cold start). */
+  readonly uptimeStartedAt: number;
+  /**
+   * Optional high-water marks for `265 RPL_LOCALUSERS` / `266
+   * RPL_GLOBALUSERS`. When omitted the live count is reported as the max
+   * (so the wire numeric never claims a max below the current count).
+   */
+  readonly maxLocalConns?: number;
+  readonly maxGlobalConns?: number;
+}
+
+export class AwsStats {
+  private readonly dynamo: DynamoDBDocumentClient;
+  private readonly tables: TablesConfig;
+  private readonly uptimeStartedAt: number;
+  private readonly maxLocalConns: number | undefined;
+  private readonly maxGlobalConns: number | undefined;
+
+  constructor(opts: AwsStatsOptions) {
+    this.dynamo = opts.dynamo;
+    this.tables = opts.tables;
+    this.uptimeStartedAt = opts.uptimeStartedAt;
+    this.maxLocalConns = opts.maxLocalConns;
+    this.maxGlobalConns = opts.maxGlobalConns;
+  }
+
+  async getStats(): Promise<ServerStatsSnapshot> {
+    // Scan Connections in a single request. DynamoDB Local + production
+    // both paginate at 1MB; for the serverless-IRC scale (≤ tens of
+    // thousands of connections per deployment) a single page covers the
+    // realistic ceiling. A deployment that outgrows this should maintain
+    // rolling count records (updated on connect/disconnect) rather than
+    // Scan — a tracked follow-up.
+    const connResult = await this.dynamo.send(
+      new ScanCommand({ TableName: this.tables.Connections }),
+    );
+    const connItems = (connResult.Items ?? []) as unknown as MarshalledConnection[];
+    const connections = connItems.map(unmarshalConnection);
+
+    // Channel count: one row per channel in `ChannelMeta`, again in a
+    // single page (channel counts are small).
+    const chanResult = await this.dynamo.send(
+      new ScanCommand({ TableName: this.tables.ChannelMeta, Select: 'COUNT' }),
+    );
+    const channelCount = chanResult.Count ?? 0;
+
+    return computeStatsSnapshot(connections, channelCount, this.uptimeStartedAt, {
+      ...(this.maxLocalConns !== undefined ? { maxLocalConns: this.maxLocalConns } : {}),
+      ...(this.maxGlobalConns !== undefined ? { maxGlobalConns: this.maxGlobalConns } : {}),
+    });
+  }
+}

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

@@ -10,7 +10,8 @@
  */
 
 import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
-import { DEFAULT_SERVER_CONFIG } from '@serverless-ircd/irc-core';
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import { makeTestServerConfig } from '@serverless-ircd/irc-test-support';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import {
   loadDynamoAccountStore,
@@ -126,6 +127,48 @@ describe.skipIf(!available)('Accounts table round-trip', () => {
       false,
     );
   });
+
+  it('silently skips rows with missing or wrong-typed credential fields', async () => {
+    // The scan path must tolerate partially-malformed rows (legacy seeds,
+    // schema drift) without throwing — it just skips them. Each branch of
+    // the per-field `typeof === 'string'` guard is exercised by writing a
+    // row where exactly one non-key field has the wrong type. (The
+    // `account` field is the partition key, so DynamoDB itself enforces
+    // its type at write time and the false branch is not exercisable
+    // through the SDK; that branch is a defensive guard against
+    // synthetically-shaped Scan results.)
+    const client = requireFx().client;
+    const table = requireFx().tableName;
+    // Well-formed row — must survive.
+    await putAccountCredential(client, table, 'good', 's3cret');
+    // Row with non-string `algorithm`.
+    await client.send(
+      new PutCommand({
+        TableName: table,
+        Item: { account: 'noalgo', algorithm: 7, salt: 's', hash: 'h' },
+      }),
+    );
+    // Row with non-string `salt`.
+    await client.send(
+      new PutCommand({
+        TableName: table,
+        Item: { account: 'nosalt', algorithm: 'SCRYPT-SHA-256', salt: false, hash: 'h' },
+      }),
+    );
+    // Row with non-string `hash`.
+    await client.send(
+      new PutCommand({
+        TableName: table,
+        Item: { account: 'nohash', algorithm: 'SCRYPT-SHA-256', salt: 's', hash: null },
+      }),
+    );
+    const store = await loadDynamoAccountStore(client, table);
+    expect(store).toBeDefined();
+    expect(store?.size).toBe(1);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'good', password: 's3cret' }).ok).toBe(
+      true,
+    );
+  });
 });
 
 describe.skipIf(!available)('resolveAccountStore precedence', () => {
@@ -139,10 +182,9 @@ describe.skipIf(!available)('resolveAccountStore precedence', () => {
 
   it('returns a DynamoAccountStore when the table has rows (table wins)', async () => {
     await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'table-secret');
-    const cfgWithSasl = {
-      ...DEFAULT_SERVER_CONFIG,
+    const cfgWithSasl = makeTestServerConfig({
       saslAccounts: [{ username: 'envuser', password: 'env-secret' }],
-    };
+    });
     const store = await resolveAccountStore(requireFx().client, requireFx().tableName, cfgWithSasl);
     expect(store).toBeDefined();
     // Table account verifies; config account does NOT (table is authoritative).
@@ -155,10 +197,9 @@ describe.skipIf(!available)('resolveAccountStore precedence', () => {
   });
 
   it('falls back to the config-seeded store when the table is empty', async () => {
-    const cfgWithSasl = {
-      ...DEFAULT_SERVER_CONFIG,
+    const cfgWithSasl = makeTestServerConfig({
       saslAccounts: [{ username: 'envuser', password: 'env-secret' }],
-    };
+    });
     const store = await resolveAccountStore(requireFx().client, requireFx().tableName, cfgWithSasl);
     expect(store).toBeDefined();
     expect(
@@ -170,7 +211,7 @@ describe.skipIf(!available)('resolveAccountStore precedence', () => {
     const store = await resolveAccountStore(
       requireFx().client,
       requireFx().tableName,
-      DEFAULT_SERVER_CONFIG,
+      makeTestServerConfig(),
     );
     expect(store).toBeUndefined();
   });

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

@@ -1,9 +1,6 @@
 import { DynamoDBDocumentClient, PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
-import {
-  DEFAULT_SERVER_CONFIG,
-  type ParsedServerConfig,
-  type SaslPayload,
-} from '@serverless-ircd/irc-core';
+import type { ParsedServerConfig, SaslPayload } from '@serverless-ircd/irc-core';
+import { makeTestServerConfig } from '@serverless-ircd/irc-test-support';
 import { mockClient } from 'aws-sdk-client-mock';
 import { describe, expect, it } from 'vitest';
 import {
@@ -21,7 +18,7 @@ function plainPayload(username: string, password: string): SaslPayload {
 
 /** Builds a minimal parsed config with the supplied saslAccounts. */
 function configWith(accounts: Array<{ username: string; password: string }>): ParsedServerConfig {
-  return { ...DEFAULT_SERVER_CONFIG, saslAccounts: accounts };
+  return makeTestServerConfig({ saslAccounts: accounts });
 }
 
 // ---------------------------------------------------------------------------
@@ -184,7 +181,7 @@ describe('resolveAccountStore', () => {
       'Accounts',
       fallback === undefined
         ? undefined
-        : { ...DEFAULT_SERVER_CONFIG, saslAccounts: [{ username: 'envuser', password: 'env-pw' }] },
+        : makeTestServerConfig({ saslAccounts: [{ username: 'envuser', password: 'env-pw' }] }),
     );
     expect(store).toBeDefined();
     expect(store?.verify('PLAIN', plainPayload('alice', 's3cret')).ok).toBe(true);

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

@@ -53,8 +53,11 @@ const endpoint = process.env.DYNAMO_ENDPOINT;
 
 /**
  * Factory entry — appends to a suite's FACTORIES array to opt the scenarios
- * into the AWS matrix. Returns a no-op factory when DynamoDB Local is
- * unavailable so `describe.skipIf` short-circuits before any test runs.
+ * into the AWS matrix. The whole describe block is gated by
+ * `describe.skipIf(process.env.DDB_AVAILABLE !== '1')` at the call site
+ * (see `aws-integration.test.ts`), so no scenarios run when DynamoDB
+ * Local is unavailable. This factory itself assumes DDB is up; its
+ * `create()` throws if `DYNAMO_ENDPOINT` was never set.
  */
 export const awsHarnessFactory: IrcHarnessFactory = Object.freeze({
   name: 'aws+ws',

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

@@ -6,12 +6,16 @@
  * a fresh {@link AwsHarness} which mints uniquely-prefixed DynamoDB
  * tables against the global-setup's endpoint.
  *
- * Gated on `process.env.DDB_AVAILABLE`: the suite is skipped when
- * DynamoDB Local cannot be booted (no Docker, no Java). When available,
- * every scenario MUST pass — that is the 040 acceptance criterion.
+ * Gated on `process.env.DDB_AVAILABLE`: the whole suite is skipped via
+ * `describe.skipIf` when DynamoDB Local cannot be booted (no Docker, no
+ * Java). When available, every scenario MUST pass — that is the
+ * acceptance criterion.
  */
 
 import { runIrcScenarios } from '@serverless-ircd/irc-test-support';
+import { describe } from 'vitest';
 import { awsHarnessFactory } from './aws-harness.js';
 
-runIrcScenarios([awsHarnessFactory]);
+describe.skipIf(process.env.DDB_AVAILABLE !== '1')('aws integration scenarios', () => {
+  runIrcScenarios([awsHarnessFactory]);
+});