serverless-ircd 0.9.0 → 0.11.0

package/packages/aws-adapter/src/cdk-table-defs.ts

@@ -18,22 +18,34 @@
  *     so a future `TransactWriteItems` can span Connections ↔ membership
  *     atomically. (Atomicity across Connections/ChannelMembers lands in the
  *     membership-transaction follow-up.)
- *   • `Accounts` stores SASL PLAIN credentials as scrypt
- *     `HashedAccountCredential` rows (`{ account, algorithm, salt,
- *     hash }`, base64) — never plaintext. Loaded at Lambda cold start
- *     by `loadDynamoAccountStore` and seeded via
- *     `putAccountCredential`.
+ *   • SASL / NickServ credentials live in the `Services` table under the
+ *     `NICK:<fold>` partition. The standalone `Accounts` table was dropped
+ *     — `ServicesStore` (`registerNick` / `verifyNick` / `verifyCertFP`)
+ *     is the single credential home for SASL PLAIN, SASL EXTERNAL,
+ *     PASS-auth, and NickServ IDENTIFY.
  *   • `Connections.idleSince` is the DynamoDB TTL attribute; idle connections
  *     are reaped automatically in addition to the explicit sweeper.
  */
 
-import { AttributeType, BillingMode } from 'aws-cdk-lib/aws-dynamodb';
-import type { TableProps } from 'aws-cdk-lib/aws-dynamodb';
-import type { TableName } from './tables.js';
+import { AttributeType, BillingMode, ProjectionType } from 'aws-cdk-lib/aws-dynamodb';
+import type { GlobalSecondaryIndexProps, TableProps } from 'aws-cdk-lib/aws-dynamodb';
+import { SOURCE_IP_INDEX_NAME, type TableName } from './tables.js';
 
 /**
- * All five tables keyed by their logical construct id. The id doubles as the
- * CloudFormation logical id; the physical `TableName` is set on each entry.
+ * A table definition: the CDK `TableProps` plus an optional side-channel
+ * for secondary indexes. Current aws-cdk-lib moved GSI declaration out
+ * of `TableProps` (indexes are added via `Table.addGlobalSecondaryIndex`
+ * after construction), so the index list rides alongside the construct
+ * props here — the stack pops it before constructing the `Table` and the
+ * DynamoDB Local fixtures read it when issuing raw `CreateTableCommand`s.
+ */
+export interface TableDef extends TableProps {
+  globalSecondaryIndexes?: GlobalSecondaryIndexProps[];
+}
+
+/**
+ * All four tables keyed by their logical construct id. The id doubles as
+ * the CloudFormation logical id; the physical `TableName` is set on each entry.
  *
  * NOTE: the deployed physical name is **environment-prefixed** by
  * `IrcAwsStack` (`<Env><LogicalId>`, e.g. `StagingConnections`) — the
@@ -42,12 +54,28 @@ import type { TableName } from './tables.js';
  * every physical name (to isolate parallel runs) consume the
  * `TABLE_DEFS` entries' key/attribute names only.
  */
-export const TABLE_DEFS: Record<TableName, TableProps> = {
+export const TABLE_DEFS: Record<TableName, TableDef> = {
   Connections: {
     tableName: 'Connections',
     partitionKey: { name: 'connectionId', type: AttributeType.STRING },
     billingMode: BillingMode.PAY_PER_REQUEST,
     timeToLiveAttribute: 'idleSince',
+    // Per-IP admission index: `$connect` counts an IP's live connections
+    // (maxConnectionsPerIp) and its in-window establishments
+    // (perIpConnectionRate) against this GSI; the NLB new-flow gate
+    // counts the window. Rows surface in the index only when both key
+    // attributes are present (handlers stamp `sourceIp` at
+    // connect/flow-establishment; legacy rows are invisible — the caps
+    // apply from this change forward). TTL-reaped rows leave the index
+    // with them, so the index self-cleans.
+    globalSecondaryIndexes: [
+      {
+        indexName: SOURCE_IP_INDEX_NAME,
+        partitionKey: { name: 'sourceIp', type: AttributeType.STRING },
+        sortKey: { name: 'connectedSince', type: AttributeType.NUMBER },
+        projectionType: ProjectionType.ALL,
+      },
+    ],
   },
   ChannelMeta: {
     tableName: 'ChannelMeta',
@@ -65,11 +93,6 @@ export const TABLE_DEFS: Record<TableName, TableProps> = {
     partitionKey: { name: 'nickLower', type: AttributeType.STRING },
     billingMode: BillingMode.PAY_PER_REQUEST,
   },
-  Accounts: {
-    tableName: 'Accounts',
-    partitionKey: { name: 'account', type: AttributeType.STRING },
-    billingMode: BillingMode.PAY_PER_REQUEST,
-  },
   Services: {
     tableName: 'Services',
     partitionKey: { name: 'pk', type: AttributeType.STRING },

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

@@ -11,6 +11,15 @@
 
 import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
 
+/**
+ * Documented schema defaults for `perIpConnectionRate`. Duplicated here
+ * (the schema inlines its `.default(...)`) so an operator setting only
+ * one half of the knob via env gets the documented default for the other
+ * half rather than a parse error.
+ */
+const DEFAULT_PER_IP_RATE_MAX = 5;
+const DEFAULT_PER_IP_RATE_WINDOW_MS = 60_000;
+
 /**
  * The subset of `process.env` this loader reads. Optional members are
  * omitted from the input object when undefined so the schema's defaults
@@ -35,6 +44,20 @@ export interface LambdaConfigEnv {
   CHANNEL_PREFIXES?: string;
   OPER_USER?: string;
   OPER_PASSWORD?: string;
+  /**
+   * Scrypt salt (base64) for the hashed oper credential form. When set
+   * alongside `OPER_USER` + `OPER_HASH`, the loader builds a hashed
+   * `{user, salt, hash}` cred instead of the legacy plaintext
+   * `{user, password}` shape. The hashed form is preferred when both
+   * are present so deployments can rotate without removing the legacy
+   * vars in the same step. Generate via `tools/hash-oper-cred.ts`.
+   */
+  OPER_SALT?: string;
+  /**
+   * Scrypt hash (base64) for the hashed oper credential form. See
+   * `OPER_SALT` for the full set of vars.
+   */
+  OPER_HASH?: string;
   /**
    * Server-password gate. Treat as an AWS secret (Secrets Manager or
    * SSM `SecureString`); the loader threads it through to
@@ -53,10 +76,62 @@ export interface LambdaConfigEnv {
   /**
    * SASL PLAIN accounts. Newline-delimited `username:password` pairs
    * (same convention as the CF adapter's `SASL_ACCOUNTS`). Parsed into
-   * the `saslAccounts` config field so {@link bindAccountStore} can seed
-   * an `InMemoryAccountStore` at boot.
+   * the `saslAccounts` config field so the boot path can seed the
+   * `ServicesStore` via `registerNick`.
    */
   SASL_ACCOUNTS?: string;
+  /**
+   * Comma-separated allowlist of web origins permitted to open
+   * WebSocket upgrades (Cross-Site WebSocket Hijacking defence —
+   * browsers send `Origin` on every cross-origin upgrade; WebSocket
+   * upgrades do not otherwise enforce same-origin, and API Gateway
+   * WebSocket has no built-in Origin check). Mirrors the CF Worker's
+   * `WEB_ORIGINS` env.
+   *
+   * Only read by the `$connect` handler at
+   * {@link buildDepsFromEnv} — it is NOT threaded through the shared
+   * `ServerConfig` schema (it is an adapter-level operational concern,
+   * not a server-config knob). When unset/empty, the defence is
+   * disabled and every Origin proceeds (the default — opt-in).
+   * Non-browser clients (curl, WeeChat, the `tcp-ws-forwarder`) never
+   * send `Origin` and always pass through regardless.
+   */
+  WEB_ORIGINS?: string;
+  /**
+   * Per-connection inbound frame window ceiling enforced by the
+   * `$default` handler BEFORE the actor / DynamoDB write. Parsed into
+   * `ServerConfig.adapter.maxFramesPerWindow`.
+   */
+  MAX_FRAMES_PER_WINDOW?: string;
+  /**
+   * Sliding-window length (seconds) for the inbound frame limit; frames
+   * older than the window stop counting. Parsed into
+   * `ServerConfig.adapter.frameWindowSeconds`.
+   */
+  FRAME_WINDOW_SECONDS?: string;
+  /**
+   * Per-IP simultaneous-connection cap (`maxConnectionsPerIp`). Enforced
+   * by the `$connect` admission gate against the `sourceIp` GSI; mirrors
+   * the CF loader's var of the same name.
+   */
+  MAX_CONNECTIONS_PER_IP?: string;
+  /**
+   * Per-IP connection-rate budget (`perIpConnectionRate.max`) — how many
+   * new connections one source IP may open per sliding window. Enforced
+   * by `$connect` and the NLB new-flow gate. The unset half of the knob
+   * falls back to the schema default.
+   */
+  PER_IP_CONNECTION_RATE_MAX?: string;
+  /** Sliding window length in ms (`perIpConnectionRate.windowMs`). */
+  PER_IP_CONNECTION_RATE_WINDOW_MS?: string;
+  /**
+   * Operator opt-in for certificate-backed SASL EXTERNAL. 'true'/'1'
+   * (case-insensitive) map to `sasl.externalEnabled: true`; any other
+   * value (and unset) leaves the mechanism off. EXTERNAL additionally
+   * requires edge mTLS (APIGW client certs on the custom domain) and a
+   * secure (TLS) connection — the flag alone advertises nothing.
+   */
+  EXTERNAL_ENABLED?: string;
 }
 
 /**
@@ -88,12 +163,36 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
     input.channelPrefixes = env.CHANNEL_PREFIXES;
   }
   if (env.OPER_USER !== undefined || env.OPER_PASSWORD !== undefined) {
-    input.operCreds = [
-      {
-        user: env.OPER_USER ?? '',
-        password: env.OPER_PASSWORD ?? '',
-      },
-    ];
+    // Hashed form (OPER_USER + OPER_SALT + OPER_HASH) is preferred when
+    // both salt + hash are supplied — even if OPER_PASSWORD is also set,
+    // so a deployment can rotate to the hashed form without dropping the
+    // legacy var in the same release. The legacy plaintext
+    // `{user, password}` shape is retained for a single deprecation-
+    // cycle window.
+    const hasHashed = env.OPER_SALT !== undefined && env.OPER_HASH !== undefined;
+    if (hasHashed) {
+      input.operCreds = [
+        {
+          user: env.OPER_USER ?? '',
+          salt: env.OPER_SALT ?? '',
+          hash: env.OPER_HASH ?? '',
+        },
+      ];
+    } else {
+      // Build the legacy cred object from whatever was supplied; the
+      // schema surfaces a `user`/`password` error if only one half was
+      // provided. If only OPER_SALT/OPER_HASH (partial) are set, the
+      // schema will surface the missing hashed-form field via the
+      // superRefine error path.
+      input.operCreds = [
+        {
+          user: env.OPER_USER ?? '',
+          password: env.OPER_PASSWORD ?? '',
+          ...(env.OPER_SALT !== undefined ? { salt: env.OPER_SALT } : {}),
+          ...(env.OPER_HASH !== undefined ? { hash: env.OPER_HASH } : {}),
+        },
+      ];
+    }
   }
   if (env.SERVER_PASSWORD !== undefined) {
     input.serverPassword = env.SERVER_PASSWORD;
@@ -122,9 +221,55 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
   if (env.SASL_ACCOUNTS !== undefined && env.SASL_ACCOUNTS.length > 0) {
     input.saslAccounts = parseSaslAccountsLines(env.SASL_ACCOUNTS);
   }
+  if (env.MAX_FRAMES_PER_WINDOW !== undefined || env.FRAME_WINDOW_SECONDS !== undefined) {
+    // Partial sections are fine: the per-field schema defaults fill the
+    // knob(s) the env did not supply.
+    input.adapter = {
+      ...(env.MAX_FRAMES_PER_WINDOW !== undefined
+        ? { maxFramesPerWindow: Number.parseInt(env.MAX_FRAMES_PER_WINDOW, 10) }
+        : {}),
+      ...(env.FRAME_WINDOW_SECONDS !== undefined
+        ? { frameWindowSeconds: Number.parseInt(env.FRAME_WINDOW_SECONDS, 10) }
+        : {}),
+    };
+  }
+  if (env.MAX_CONNECTIONS_PER_IP !== undefined) {
+    input.maxConnectionsPerIp = Number.parseInt(env.MAX_CONNECTIONS_PER_IP, 10);
+  }
+  if (
+    env.PER_IP_CONNECTION_RATE_MAX !== undefined ||
+    env.PER_IP_CONNECTION_RATE_WINDOW_MS !== undefined
+  ) {
+    // The schema requires both halves; the unset one falls back to the
+    // documented schema defaults (mirrors the CF loader's vars of the
+    // same names so operators tune both platforms identically).
+    input.perIpConnectionRate = {
+      max:
+        env.PER_IP_CONNECTION_RATE_MAX !== undefined
+          ? Number.parseInt(env.PER_IP_CONNECTION_RATE_MAX, 10)
+          : DEFAULT_PER_IP_RATE_MAX,
+      windowMs:
+        env.PER_IP_CONNECTION_RATE_WINDOW_MS !== undefined
+          ? Number.parseInt(env.PER_IP_CONNECTION_RATE_WINDOW_MS, 10)
+          : DEFAULT_PER_IP_RATE_WINDOW_MS,
+    };
+  }
+  if (env.EXTERNAL_ENABLED !== undefined) {
+    input.sasl = { externalEnabled: parseEnabledFlag(env.EXTERNAL_ENABLED) };
+  }
   return input;
 }
 
+/**
+ * Parses a boolean feature-flag env var: 'true' / '1' (case-insensitive,
+ * whitespace-trimmed) are truthy; every other value is false. Flags
+ * default off, so a typo must never silently enable the feature.
+ */
+function parseEnabledFlag(raw: string): boolean {
+  const normalized = raw.trim().toLowerCase();
+  return normalized === 'true' || normalized === '1';
+}
+
 /**
  * Parses the `CREATED_AT` env var into the schema's `createdAt` field.
  *

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

@@ -198,6 +198,9 @@ export class DynamoServicesStore extends PersistentServicesStore {
       email: row.email,
       createdAt: row.createdAt,
       enforce: row.enforce,
+      certSubjects: row.certSubjects ?? [],
+      identifyFailures: row.identifyFailures ?? [],
+      pendingIdentifyFailureNotice: row.pendingIdentifyFailureNotice ?? 0,
       algorithm: row.credential.algorithm,
       salt: row.credential.salt,
       hash: row.credential.hash,
@@ -536,12 +539,28 @@ function coerceNick(item: Record<string, unknown>): ServicesNickRow | undefined
   ) {
     return undefined;
   }
+  // certSubjects is additive — older rows written before the column existed
+  // load as []. Accepts a JSON-array or a string[]; anything else → [].
+  const certSubjects = Array.isArray(item.certSubjects)
+    ? item.certSubjects.filter((s): s is string => typeof s === 'string')
+    : [];
+  // The identify-throttle fields are additive in the same way: absent (a
+  // pre-throttle item) or ill-typed attributes collapse to the neutral
+  // unfrozen defaults.
+  const identifyFailures = Array.isArray(item.identifyFailures)
+    ? item.identifyFailures.filter((t): t is number => typeof t === 'number')
+    : [];
+  const pendingIdentifyFailureNotice =
+    typeof item.pendingIdentifyFailureNotice === 'number' ? item.pendingIdentifyFailureNotice : 0;
   return {
     nick: item.nick,
     account: item.account,
     email: item.email,
     createdAt: item.createdAt,
     enforce: item.enforce as NickEnforcePolicy,
+    certSubjects,
+    identifyFailures,
+    pendingIdentifyFailureNotice,
     credential: {
       account: item.account,
       algorithm: 'scrypt',

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

@@ -24,6 +24,8 @@ import {
 } from '@serverless-ircd/irc-core';
 import { type AdmissionOutcome, decideConnectAdmission } from '../admission.js';
 import { decrementConnectionCount, incrementConnectionCount } from '../connection-counter.js';
+import { countConnectionsForIp } from '../ip-admission.js';
+import { decideConnectOrigin } from '../origin-allowlist.js';
 import { marshalConnection } from '../serialize.js';
 import type { TablesConfig } from '../tables.js';
 import { createInitialConnectionState } from './state.js';
@@ -44,6 +46,32 @@ export interface ConnectParams {
    * none match or the header is absent).
    */
   secWebSocketProtocol?: string | null;
+  /**
+   * Raw `Origin` header from `event.headers.Origin` (case-insensitive).
+   * When {@link ConnectParams.webOrigins} is non-empty and this is a
+   * browser-sent origin that is not on the allowlist, the upgrade is
+   * rejected with `403` (Cross-Site WebSocket Hijacking defence —
+   * API Gateway has no built-in Origin check). `null` / `undefined`
+   * (non-browser clients: curl, WeeChat, the `tcp-ws-forwarder`)
+   * always proceed; the defence is opt-in (only fires when the
+   * allowlist is non-empty).
+   */
+  originHeader?: string | null | undefined;
+  /**
+   * Parsed `WEB_ORIGINS` allowlist. Empty set (or `undefined`) disables
+   * the Origin check (the default — defence is opt-in).
+   */
+  webOrigins?: Set<string> | undefined;
+  /**
+   * Source IP of the connecting client (`event.requestContext.identity
+   * .sourceIp` on APIGW). When present, the per-IP admission gates run:
+   * a paginated Query against the `sourceIp` GSI supplies the IP's live
+   * count (`maxConnectionsPerIp`) and its in-window count
+   * (`perIpConnectionRate`), and the previously-dormant per-IP branch
+   * of {@link decideConnectAdmission} goes live. Absent (older event
+   * shapes) the per-IP checks are skipped entirely.
+   */
+  sourceIp?: string | null | undefined;
 }
 
 /**
@@ -83,11 +111,49 @@ export async function handleConnect(params: ConnectParams): Promise<ConnectOutco
   const now = params.now ?? Date.now();
   const maxClients = params.serverConfig.maxClients;
 
+  // CSWSH defence — Origin allowlist. Runs before the admission counter
+  // so a hostile-origin flood cannot consume `maxClients` slots. Only
+  // fires when `WEB_ORIGINS` is set (defence is opt-in); a missing
+  // `Origin` header (non-browser clients) always proceeds.
+  const originDecision = decideConnectOrigin(params.originHeader, params.webOrigins ?? new Set());
+  if (originDecision === 'deny') {
+    return { admitted: false, statusCode: 403, reason: 'origin not allowed' };
+  }
+
+  // Per-IP admission counts (GSI walk). Runs before the global counter
+  // reservation so an over-budget IP never churns the meta-row counter.
+  // An empty/absent source IP skips the per-IP gates (branch stays
+  // dormant, matching pre-GSI event shapes).
+  let perIp: number | undefined;
+  let recentPerIp: number | undefined;
+  if (typeof params.sourceIp === 'string' && params.sourceIp.length > 0) {
+    const ipCounts = await countConnectionsForIp(
+      params.dynamo,
+      params.tables.Connections,
+      params.sourceIp,
+      now,
+      params.serverConfig.perIpConnectionRate.windowMs,
+    );
+    perIp = ipCounts.total;
+    recentPerIp = ipCounts.recent;
+  }
+
   // Reserve a slot atomically. The returned value includes this reservation,
   // so the pre-existing count (`total`, as expected by the policy) is one
   // less than the post-increment value.
   const reservedCount = await incrementConnectionCount(params.dynamo, params.tables.Connections);
-  const outcome = decideConnectAdmission({ total: reservedCount - 1 }, { maxClients });
+  const outcome = decideConnectAdmission(
+    {
+      total: reservedCount - 1,
+      ...(perIp !== undefined ? { perIp } : {}),
+      ...(recentPerIp !== undefined ? { recentPerIp } : {}),
+    },
+    {
+      maxClients,
+      maxConnectionsPerIp: params.serverConfig.maxConnectionsPerIp,
+      perIpRate: params.serverConfig.perIpConnectionRate,
+    },
+  );
   if (!outcome.admitted) {
     // Over capacity — release the reservation so the counter does not drift
     // upward on every rejected connect.
@@ -118,6 +184,12 @@ export async function handleConnect(params: ConnectParams): Promise<ConnectOutco
   if (mode !== 'legacy') {
     row.wsMode = mode;
   }
+  // Persist the source IP so the `sourceIp` GSI carries this connection
+  // for future per-IP admission walks (rows without it are invisible to
+  // the index — see ip-admission.ts).
+  if (typeof params.sourceIp === 'string' && params.sourceIp.length > 0) {
+    row.sourceIp = params.sourceIp;
+  }
   try {
     await params.dynamo.send(
       new PutCommand({