serverless-ircd 0.3.0 → 0.5.0

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

@@ -0,0 +1,74 @@
+/**
+ * Pure admission policy for the AWS `$connect` handler.
+ *
+ * The I/O (counting live rows in DynamoDB) lives in `handlers/connect.ts`;
+ * the *decision* — "does this count fit under the caps?" — is a pure
+ * function extracted here so it is trivial to unit-test every branch
+ * without standing up DynamoDB Local.
+ *
+ * This is deliberately separate from irc-core's `decideAdmission` /
+ * `AdmissionStats`: that helper is an in-memory counter design that
+ * assumes a single long-lived process. AWS Lambda invocations are
+ * independent processes with no shared memory, so the authoritative
+ * counts MUST come from DynamoDB (the shared `Connections` table) and
+ * are fed into this pure policy.
+ */
+
+/**
+ * Live connection counts gathered from DynamoDB.
+ *
+ *   - `total` is always supplied (a paginated `Scan COUNT` over
+ *     `Connections`).
+ *   - `perIp` is optional: counting connections per source IP needs a
+ *     GSI on `sourceIp` (see `handlers/connect.ts` for the deferred
+ *     per-IP follow-up). Until that lands, callers omit `perIp` and the
+ *     per-IP branch of {@link decideConnectAdmission} is skipped.
+ */
+export interface ConnectionCounts {
+  readonly total: number;
+  readonly perIp?: number;
+}
+
+/**
+ * Effective caps sourced from {@link ParsedServerConfig}. `perIp` is
+ * optional because per-IP enforcement is not yet wired on the AWS path.
+ */
+export interface AdmissionLimits {
+  readonly maxClients: number;
+  readonly maxConnectionsPerIp?: number;
+}
+
+/**
+ * Outcome of an admission decision. Mirrors the {@link ConnectOutcome}
+ * shape returned by `handleConnect` so the handler can return the
+ * decision verbatim.
+ */
+export type AdmissionOutcome =
+  | { readonly admitted: true }
+  | { readonly admitted: false; readonly statusCode: number; readonly reason: string };
+
+/**
+ * Decides whether a new connection should be admitted given the live
+ * counts and the configured caps. Pure: same inputs ⇒ same output, no
+ * ambient state.
+ *
+ * Precedence: the global `maxClients` cap is checked first (it is the
+ * cheap, always-available gate), then the optional per-IP cap when both
+ * the limit and the `perIp` count are present.
+ */
+export function decideConnectAdmission(
+  counts: ConnectionCounts,
+  limits: AdmissionLimits,
+): AdmissionOutcome {
+  if (counts.total >= limits.maxClients) {
+    return { admitted: false, statusCode: 429, reason: 'server full' };
+  }
+  if (
+    limits.maxConnectionsPerIp !== undefined &&
+    counts.perIp !== undefined &&
+    counts.perIp >= limits.maxConnectionsPerIp
+  ) {
+    return { admitted: false, statusCode: 429, reason: 'too many connections from this IP' };
+  }
+  return { admitted: true };
+}

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

@@ -51,6 +51,7 @@ import {
   type Nick,
   type RawLine,
   type RosterEntry,
+  type ServerConfig,
   SystemClock,
   emptyModes,
   toSnapshot as toConnSnapshot,
@@ -80,7 +81,8 @@ import type { TablesConfig } from './tables.js';
  *     is the in-memory `received` array.
  *   - `disconnect(reason?)` closes the bound transport. In Lambda this
  *     is a no-op — the canonical disconnect path is the APIGW `$disconnect`
- *     route, which fires after the socket is already gone.
+ *     route, which fires after the socket is already gone. See
+ *     `docs/AWS-Deployment.md` §14.1 for the full platform-limit write-up.
  *   - `snapshot()` returns the in-memory ConnectionState the actor is
  *     mutating this frame. Critical so `getConnection(boundId)` returns
  *     the live view (and dispatch's reducer-observable effects see
@@ -118,6 +120,14 @@ export interface AwsRuntimeOptions {
    */
   managementApi: ApiGatewayManagementApi | PostToConnection | null;
   clock?: Clock;
+  /**
+   * Config-reload source for `REHASH`. The Lambda handler binds this to a
+   * closure that re-invokes {@link loadServerConfigFromLambdaEnv} against the
+   * invocation env (Secrets Manager / SSM / env vars). When omitted
+   * `reloadConfig` rejects so the actor applies a graceful error-suffixed
+   * `382` and retains the prior config.
+   */
+  readonly configLoader?: () => Promise<ServerConfig>;
 }
 
 /**
@@ -132,6 +142,7 @@ export class AwsRuntime implements IrcRuntime {
   private readonly handlers: AwsRuntimeHandlers;
   private readonly managementApi: ApiGatewayManagementApi | PostToConnection | null;
   private readonly clock: Clock;
+  private readonly configLoader: (() => Promise<ServerConfig>) | undefined;
 
   constructor(opts: AwsRuntimeOptions) {
     this.dynamo = opts.dynamo;
@@ -140,6 +151,7 @@ export class AwsRuntime implements IrcRuntime {
     this.handlers = opts.handlers;
     this.managementApi = opts.managementApi;
     this.clock = opts.clock ?? SystemClock;
+    this.configLoader = opts.configLoader;
   }
 
   // -------------------------------------------------------------------------
@@ -185,11 +197,12 @@ export class AwsRuntime implements IrcRuntime {
       this.handlers.disconnect(reason);
       return;
     }
-    // Cross-connection disconnect is a no-op in 040: the Lambda runtime
-    // cannot directly close another connection's WebSocket. The canonical
+    // Cross-connection disconnect is a no-op: the Lambda runtime cannot
+    // directly close another connection's WebSocket. The canonical
     // disconnect path is the APIGW `$disconnect` route, which fires when
     // the socket is already gone. KICK/PART remove membership rows but
-    // do not need to force-close the socket.
+    // do not need to force-close the socket. See docs/AWS-Deployment.md
+    // §14.1 for the full platform-limit write-up and the mitigations.
   }
 
   async sendToNick(
@@ -208,6 +221,51 @@ export class AwsRuntime implements IrcRuntime {
     }
   }
 
+  /**
+   * Global cross-connection fan-out for `WALLOPS`. `Scan`s the `Connections`
+   * table filtered to rows whose `userModes.wallops` is `true`, then
+   * `PostToConnection`s each one (skipping `except`). The bound connection's
+   * own delivery goes through the in-process handlers (no APIGW round-trip),
+   * mirroring `send`.
+   *
+   * Cost: a DynamoDB `Scan` reads the ENTIRE table (chargeable per row read,
+   * not per match), so this is expensive at high connection counts. A fleet
+   * of 10k connections costs one full scan per WALLOPS plus one
+   * `PostToConnection` per `+w` recipient. Deployments should bound the
+   * oper's WALLOPS rate; a projected GSI on `userModes.wallops` would lift
+   * the scan to a targeted query (documented follow-up). The scan uses
+   * `FilterExpression` so only `+w` rows survive to the `PostToConnection`
+   * phase — the APIGW call count is bounded by the genuine recipient set.
+   */
+  async broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void> {
+    let startKey: Record<string, NativeAttributeValue> | undefined;
+    // Paginate the scan: DynamoDB caps a single Scan at 1 MB. Loop until
+    // no `LastEvaluatedKey` remains so every +w connection is reached.
+    do {
+      const result = await this.dynamo.send(
+        new ScanCommand({
+          TableName: this.tables.Connections,
+          FilterExpression: 'userModes.#m = :true',
+          ExpressionAttributeNames: { '#m': 'wallops' },
+          ExpressionAttributeValues: { ':true': true },
+          ...(startKey !== undefined ? { ExclusiveStartKey: startKey } : {}),
+        }),
+      );
+      const items = (result.Items ?? []) as unknown as MarshalledConnection[];
+      for (const row of items) {
+        const connId = row.connectionId;
+        if (connId === except) continue;
+        // `send` short-cuts the bound connection through the in-process
+        // handlers and catches GoneException so vanished sockets are
+        // cleaned up rather than aborting the fan-out mid-loop.
+        if (row.userModes.wallops) {
+          await this.send(connId, lines);
+        }
+      }
+      startKey = result.LastEvaluatedKey as Record<string, NativeAttributeValue> | undefined;
+    } while (startKey !== undefined);
+  }
+
   // -------------------------------------------------------------------------
   // Nick registry
   // -------------------------------------------------------------------------
@@ -363,6 +421,19 @@ export class AwsRuntime implements IrcRuntime {
     return out;
   }
 
+  /**
+   * Re-invokes the bound config loader (Secrets Manager / SSM / env) and
+   * returns the fresh {@link ServerConfig}. The Lambda handler binds the
+   * loader at construction; when no loader was supplied this rejects so the
+   * actor's graceful failure path applies.
+   */
+  async reloadConfig(): Promise<ServerConfig> {
+    if (this.configLoader === undefined) {
+      throw new Error('no config loader bound to AwsRuntime');
+    }
+    return this.configLoader();
+  }
+
   // -------------------------------------------------------------------------
   // Public helpers (re-exported surface)
   // -------------------------------------------------------------------------

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

@@ -19,6 +19,17 @@ import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc
 export interface LambdaConfigEnv {
   SERVER_NAME?: string;
   NETWORK_NAME?: string;
+  /**
+   * Server version surfaced in `002`/`004`/`351`/`371`. When unset the
+   * schema default ({@link DEFAULT_SERVER_VERSION}) applies.
+   */
+  SERVER_VERSION?: string;
+  /**
+   * "Created" text for `003 RPL_CREATED`. A numeric string is parsed into
+   * an epoch-ms number so the reducer formats it as a UTC timestamp; any
+   * other value is passed through verbatim.
+   */
+  CREATED_AT?: string;
   MOTD?: string;
   MAX_CLIENTS?: string;
   CHANNEL_PREFIXES?: string;
@@ -53,6 +64,12 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
     serverName: env.SERVER_NAME,
     networkName: env.NETWORK_NAME,
   };
+  if (env.SERVER_VERSION !== undefined) {
+    input.serverVersion = env.SERVER_VERSION;
+  }
+  if (env.CREATED_AT !== undefined) {
+    input.createdAt = parseCreatedAt(env.CREATED_AT);
+  }
   if (env.MOTD !== undefined && env.MOTD.length > 0) {
     input.motdLines = env.MOTD.split('\n');
   }
@@ -97,6 +114,21 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
   return input;
 }
 
+/**
+ * Parses the `CREATED_AT` env var into the schema's `createdAt` field.
+ *
+ * A purely numeric string is treated as epoch-ms (returned as a number so
+ * the reducer formats it as a UTC timestamp); any other value is returned
+ * verbatim as a human-readable string.
+ */
+function parseCreatedAt(raw: string): string | number {
+  if (/^\d+$/.test(raw.trim())) {
+    const n = Number(raw.trim());
+    if (Number.isFinite(n)) return n;
+  }
+  return raw;
+}
+
 /**
  * Parses a newline-delimited `username:password` string into the config's
  * `saslAccounts` shape. Malformed entries (missing colon, empty fields)

package/packages/aws-adapter/src/dynamo-account-store.ts

@@ -16,108 +16,37 @@
  * `irc-core/src/ports.ts` and used by `MotdProvider` / `MessageStore`:
  * adapters that need an async backend pre-load the data at boot into a
  * synchronously-readable store.
+ *
+ * The scrypt hashing helpers (`hashAccountCredential` /
+ * `verifyHashedPassword` + the `HashedAccountCredential` type) live in
+ * `irc-core` and are shared with the CF adapter's `D1AccountStore`. They
+ * are re-exported below so existing call sites importing from this module
+ * keep working.
  */
 
-import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
 import type { ScanCommandOutput } from '@aws-sdk/client-dynamodb';
 import { ScanCommand } from '@aws-sdk/lib-dynamodb';
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import type { AccountStore, SaslPayload, SaslResult } from '@serverless-ircd/irc-core';
-
-const SCRYPT_KEY_LEN = 64;
-const SALT_LEN = 16;
+import {
+  type HashedAccountCredential,
+  HashedAccountStore,
+  hashAccountCredential,
+  verifyHashedPassword,
+} from '@serverless-ircd/irc-core';
 
-/**
- * A single SASL PLAIN credential stored as a scrypt hash.
- *
- * Every field is a DynamoDB attribute — this object IS the table row
- * (plus the PK `account`). `algorithm` is retained so future migrations
- * to Argon2/bcrypt can be detected and handled gracefully.
- */
-export interface HashedAccountCredential {
-  readonly account: string;
-  readonly algorithm: 'scrypt';
-  readonly salt: string;
-  readonly hash: string;
-}
-
-/**
- * Hashes a plaintext password into a {@link HashedAccountCredential}
- * suitable for writing to the `Accounts` table via `putAccountCredential`.
- *
- * Uses `scryptSync` (memory-hard, GPU-resistant) with a random salt.
- * Pass `{ salt }` for deterministic test scenarios; pass `{ keyLen }` to
- * override the default 64-byte derived-key length.
- */
-export function hashAccountCredential(
-  username: string,
-  password: string,
-  opts?: { salt?: Buffer; keyLen?: number },
-): HashedAccountCredential {
-  const salt = opts?.salt ?? randomBytes(SALT_LEN);
-  const keyLen = opts?.keyLen ?? SCRYPT_KEY_LEN;
-  const hash = scryptSync(password, salt, keyLen);
-  return {
-    account: username,
-    algorithm: 'scrypt',
-    salt: salt.toString('base64'),
-    hash: hash.toString('base64'),
-  };
-}
+// Re-export so callers importing these from `@serverless-ircd/aws-adapter`
+// (the historical home of the hashing helpers) keep compiling.
+export { type HashedAccountCredential, hashAccountCredential, verifyHashedPassword };
 
 /**
- * Verifies a plaintext password against a {@link HashedAccountCredential}
- * using `timingSafeEqual` (no short-circuit on first mismatched byte).
+ * Synchronous {@link AccountStore} backed by pre-loaded hashed credentials.
  *
- * Returns `false` for malformed entries rather than throwing — a corrupt
- * row should not crash the SASL exchange.
+ * Now a re-export of the shared `HashedAccountStore` from `irc-core` —
+ * both adapters use one store implementation. The AWS-specific surface
+ * (`loadDynamoAccountStore`) lives below; it diverges from CF only at the
+ * scan boundary.
  */
-export function verifyHashedPassword(password: string, entry: HashedAccountCredential): boolean {
-  if (entry.algorithm !== 'scrypt') return false;
-  let salt: Buffer;
-  let expected: Buffer;
-  try {
-    salt = Buffer.from(entry.salt, 'base64');
-    expected = Buffer.from(entry.hash, 'base64');
-  } catch {
-    return false;
-  }
-  if (expected.length === 0) return false;
-  const computed = scryptSync(password, salt, expected.length);
-  return computed.length === expected.length && timingSafeEqual(computed, expected);
-}
-
-/**
- * Synchronous {@link AccountStore} backed by pre-loaded hashed
- * credentials. Construct with entries from {@link loadDynamoAccountStore}
- * (or {@link hashAccountCredential} for unit tests).
- */
-export class DynamoAccountStore implements AccountStore {
-  private readonly entries: ReadonlyMap<string, HashedAccountCredential>;
-
-  constructor(entries: ReadonlyArray<HashedAccountCredential>) {
-    this.entries = new Map(entries.map((e) => [e.account, e]));
-  }
-
-  verify(mech: string, payload: SaslPayload): SaslResult {
-    if (mech.toUpperCase() !== 'PLAIN' || payload.kind !== 'PLAIN') {
-      return { ok: false, reason: `unsupported mechanism: ${mech}` };
-    }
-    const entry = this.entries.get(payload.username);
-    if (entry === undefined) {
-      return { ok: false, reason: 'invalid credentials' };
-    }
-    if (!verifyHashedPassword(payload.password, entry)) {
-      return { ok: false, reason: 'invalid credentials' };
-    }
-    return { ok: true, account: payload.username };
-  }
-
-  /** Number of loaded accounts (diagnostics / logging). */
-  get size(): number {
-    return this.entries.size;
-  }
-}
+export { HashedAccountStore as DynamoAccountStore };
 
 /**
  * Scans the `Accounts` table and returns a fully-populated
@@ -130,7 +59,7 @@ export class DynamoAccountStore implements AccountStore {
 export async function loadDynamoAccountStore(
   docClient: DynamoDBDocumentClient,
   tableName: string,
-): Promise<DynamoAccountStore | undefined> {
+): Promise<HashedAccountStore | undefined> {
   const entries: HashedAccountCredential[] = [];
   let exclusiveStartKey: Record<string, unknown> | undefined = undefined;
   do {
@@ -145,12 +74,22 @@ export async function loadDynamoAccountStore(
       const algorithm = typeof item.algorithm === 'string' ? item.algorithm : undefined;
       const salt = typeof item.salt === 'string' ? item.salt : undefined;
       const hash = typeof item.hash === 'string' ? item.hash : undefined;
-      if (account !== undefined && algorithm !== undefined && salt !== undefined && hash !== undefined) {
-        entries.push({ account, algorithm: algorithm as HashedAccountCredential['algorithm'], salt, hash });
+      if (
+        account !== undefined &&
+        algorithm !== undefined &&
+        salt !== undefined &&
+        hash !== undefined
+      ) {
+        entries.push({
+          account,
+          algorithm: algorithm as HashedAccountCredential['algorithm'],
+          salt,
+          hash,
+        });
       }
     }
     exclusiveStartKey = result.LastEvaluatedKey;
   } while (exclusiveStartKey !== undefined);
   if (entries.length === 0) return undefined;
-  return new DynamoAccountStore(entries);
+  return new HashedAccountStore(entries);
 }

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

@@ -4,11 +4,24 @@
  * Persists a fresh `Connections` row keyed by the APIGW connection id.
  * Subsequent `$default` invocations load this row, run the actor, and
  * persist the mutated state back.
+ *
+ * Admission gate: before writing the row, the handler counts the live
+ * `Connections` rows and rejects the upgrade with `429 Too Many Requests`
+ * once `serverConfig.maxClients` is reached. A `429` (not `403`) is used
+ * because the rejection is a capacity / back-pressure signal — the client
+ * is welcome to retry — rather than an authorisation failure.
  */
 
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { PutCommand } from '@aws-sdk/lib-dynamodb';
-import type { ParsedServerConfig } from '@serverless-ircd/irc-core';
+import { PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
+import {
+  type ParsedServerConfig,
+  type WsSubprotocol,
+  parseSecWsProtocolOffers,
+  selectSubprotocol,
+  wsFrameModeFor,
+} from '@serverless-ircd/irc-core';
+import { type AdmissionOutcome, decideConnectAdmission } from '../admission.js';
 import { marshalConnection } from '../serialize.js';
 import type { TablesConfig } from '../tables.js';
 import { createInitialConnectionState } from './state.js';
@@ -20,25 +33,99 @@ export interface ConnectParams {
   connectionId: string;
   /** Wall clock used to seed `connectedSince` / `idleSince` (default: now). */
   now?: number;
-  /** Reserved for future use; required so the signature mirrors `$default`. */
-  serverConfig?: ParsedServerConfig;
+  /** Server config — consulted for the `maxClients` admission cap. */
+  serverConfig: ParsedServerConfig;
+  /**
+   * Raw `Sec-WebSocket-Protocol` header offered by the client on the
+   * `$connect` upgrade, if present. Parsed into an ordered offer list and
+   * the first supported IRCv3 subprotocol is agreed (legacy fallback when
+   * none match or the header is absent).
+   */
+  secWebSocketProtocol?: string | null;
 }
 
 /**
- * Inserts the Connections row for a fresh WebSocket upgrade.
+ * Outcome of a `$connect`. Mirrors {@link AdmissionOutcome} on the rejection
+ * branch and carries the negotiated IRCv3 {@link WsSubprotocol} on success so
+ * the dispatcher can echo it back to the client in the integration response.
+ * `subprotocol === null` signals a legacy (no-subprotocol) connection.
+ */
+export type ConnectOutcome =
+  | { readonly admitted: true; readonly subprotocol: WsSubprotocol | null }
+  | { readonly admitted: false; readonly statusCode: number; readonly reason: string };
+
+/**
+ * Enforces the `maxClients` admission cap, then inserts the Connections
+ * row for a fresh WebSocket upgrade.
+ *
+ * Idempotent on success: APIGW retries `$connect` on transient failures,
+ * so the write uses `PutCommand` (overwrites) rather than a conditional
+ * insert.
  *
- * Idempotent: APIGW retries `$connect` on transient failures, so we
- * use `PutCommand` (overwrites) rather than a conditional insert.
+ * TOCTOU note: DynamoDB cannot conditionally write based on a row count,
+ * so the count-then-put sequence has a race window. This is an accepted
+ * trade-off for an admission cap — it bounds growth under steady load
+ * rather than enforcing a hard invariant. Two concurrent upgrades that
+ * both observe `count == cap - 1` will both be admitted.
+ *
+ * Per-IP admission (`maxConnectionsPerIp`) is intentionally NOT enforced
+ * here. irc-core's in-memory `AdmissionStats` is unsuitable for Lambda
+ * (each invocation is a fresh process with no shared counters), and a
+ * filtered full-table `Scan` per `$connect` would double the DynamoDB
+ * cost on every connect (and `maxConnectionsPerIp` is on by default).
+ * The correct fix is to persist `sourceIp` on the Connections row and
+ * add a DynamoDB GSI keyed by `sourceIp`, then feed the GSI's count
+ * into {@link decideConnectAdmission}'s `perIp` branch. That schema
+ * change is tracked as a follow-up; the pure policy already supports it.
  */
-export async function handleConnect(params: ConnectParams): Promise<void> {
+export async function handleConnect(params: ConnectParams): Promise<ConnectOutcome> {
   const now = params.now ?? Date.now();
+  const total = await countConnections(params.dynamo, params.tables.Connections);
+  const outcome = decideConnectAdmission({ total }, { maxClients: params.serverConfig.maxClients });
+  if (!outcome.admitted) return outcome;
+  // IRCv3 WebSocket subprotocol negotiation: parse the offered
+  // `Sec-WebSocket-Protocol` list, select the first supported entry, and
+  // persist the resulting frame mode so every subsequent `$default`
+  // invocation recovers it (a Lambda `$connect` has no live socket to
+  // tag, unlike the CF adapter's hibernation tags). `null` means no
+  // supported subprotocol was offered → legacy framing, no mode column.
+  const chosen = selectSubprotocol(parseSecWsProtocolOffers(params.secWebSocketProtocol));
+  const mode = wsFrameModeFor(chosen ?? undefined);
   const state = createInitialConnectionState(params.connectionId, now);
-  void params.serverConfig; // reserved for max-clients gating (later ticket)
   const row = marshalConnection(state, now);
+  if (mode !== 'legacy') {
+    row.wsMode = mode;
+  }
   await params.dynamo.send(
     new PutCommand({
       TableName: params.tables.Connections,
       Item: row,
     }),
   );
+  return { admitted: true, subprotocol: chosen };
+}
+
+/**
+ * Paginated `Scan` with `Select: COUNT` over the `Connections` table.
+ * A single Scan page caps at 1MB, so the loop follows
+ * `LastEvaluatedKey` until every page has been summed.
+ */
+async function countConnections(
+  dynamo: DynamoDBDocumentClient,
+  tableName: string,
+): Promise<number> {
+  let total = 0;
+  let lastKey: unknown = undefined;
+  do {
+    const res = await dynamo.send(
+      new ScanCommand({
+        TableName: tableName,
+        Select: 'COUNT',
+        ...(lastKey !== undefined ? { ExclusiveStartKey: lastKey as never } : {}),
+      }),
+    );
+    total += res.Count ?? 0;
+    lastKey = res.LastEvaluatedKey;
+  } while (lastKey !== undefined);
+  return total;
 }