serverless-ircd 0.1.0 → 0.3.0

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

@@ -0,0 +1,73 @@
+/**
+ * CDK-coupled table definitions (PLAN §4).
+ *
+ * The single source of truth for the deployed table shapes
+ * (`partitionKey`, `sortKey`, `timeToLiveAttribute`, …). Lives in
+ * `aws-adapter` (not `aws-stack`) so the runtime can reference the same
+ * logical names via {@link TABLE_NAMES} without round-tripping through
+ * the app directory.
+ *
+ * Re-exported from `apps/aws-stack/src/aws-stack.ts`. NOT re-exported
+ * from `aws-adapter`'s `index.ts` so the Lambda handler bundle does
+ * not transitively include `aws-cdk-lib`.
+ *
+ * Schema invariants (PLAN §4):
+ *   • `Nicks` uniqueness is enforced at write-time via conditional PutItem
+ *     (PK = lowercased nick) — not by the schema itself.
+ *   • `ChannelMembers` uses a composite key (channelName PK + connectionId SK)
+ *     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`.
+ *   • `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';
+
+/**
+ * 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.
+ *
+ * NOTE: the deployed physical name is **environment-prefixed** by
+ * `IrcAwsStack` (`<Env><LogicalId>`, e.g. `StagingConnections`) — the
+ * `tableName` here is the schema default overridden at synth time. Both
+ * the CDK stack and the runtime read from this record. Tests that prefix
+ * every physical name (to isolate parallel runs) consume the
+ * `TABLE_DEFS` entries' key/attribute names only.
+ */
+export const TABLE_DEFS: Record<TableName, TableProps> = {
+  Connections: {
+    tableName: 'Connections',
+    partitionKey: { name: 'connectionId', type: AttributeType.STRING },
+    billingMode: BillingMode.PAY_PER_REQUEST,
+    timeToLiveAttribute: 'idleSince',
+  },
+  ChannelMeta: {
+    tableName: 'ChannelMeta',
+    partitionKey: { name: 'channelName', type: AttributeType.STRING },
+    billingMode: BillingMode.PAY_PER_REQUEST,
+  },
+  ChannelMembers: {
+    tableName: 'ChannelMembers',
+    partitionKey: { name: 'channelName', type: AttributeType.STRING },
+    sortKey: { name: 'connectionId', type: AttributeType.STRING },
+    billingMode: BillingMode.PAY_PER_REQUEST,
+  },
+  Nicks: {
+    tableName: 'Nicks',
+    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,
+  },
+};

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

@@ -0,0 +1,126 @@
+/**
+ * Lambda env config loader.
+ *
+ * Mirrors the Cloudflare (`cf-adapter/src/config-loader.ts`) and local-cli
+ * (`local-cli/src/config-loader.ts`) adapters: takes platform-native env
+ * vars and feeds them through the shared {@link parseServerConfig} so a
+ * single boot-time failure mode covers every adapter.
+ *
+ * Lambda env vars are all strings; numeric knobs are coerced here.
+ */
+
+import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
+
+/**
+ * The subset of `process.env` this loader reads. Optional members are
+ * omitted from the input object when undefined so the schema's defaults
+ * apply.
+ */
+export interface LambdaConfigEnv {
+  SERVER_NAME?: string;
+  NETWORK_NAME?: string;
+  MOTD?: string;
+  MAX_CLIENTS?: string;
+  CHANNEL_PREFIXES?: string;
+  OPER_USER?: string;
+  OPER_PASSWORD?: string;
+  MAX_CHANNELS_PER_USER?: string;
+  MAX_TARGETS_PER_COMMAND?: string;
+  NICK_LEN?: string;
+  CHANNEL_LEN?: string;
+  TOPIC_LEN?: string;
+  MAX_LIST_ENTRIES?: string;
+  QUIT_MESSAGE?: string;
+  /**
+   * SASL PLAIN accounts. Newline-delimited `username:password` pairs
+   * (same convention as the CF adapter's `SASL_ACCOUNTS`). Parsed into
+   * the `saslAccounts` config field so {@link bindAccountStore} can seed
+   * an `InMemoryAccountStore` at boot.
+   */
+  SASL_ACCOUNTS?: string;
+}
+
+/**
+ * Builds the input object the shared schema expects from a Lambda env.
+ *
+ * Exported so the assemble→parse boundary is unit-testable in isolation.
+ * Mirrors `cf-adapter`'s `buildConfigInput` line-for-line except for the
+ * MOTD env-var name (`MOTD` here vs `MOTD_LINES` in CF — Lambda env vars
+ * conventionally use bare names).
+ */
+export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unknown> {
+  const input: Record<string, unknown> = {
+    serverName: env.SERVER_NAME,
+    networkName: env.NETWORK_NAME,
+  };
+  if (env.MOTD !== undefined && env.MOTD.length > 0) {
+    input.motdLines = env.MOTD.split('\n');
+  }
+  if (env.MAX_CLIENTS !== undefined) {
+    input.maxClients = Number.parseInt(env.MAX_CLIENTS, 10);
+  }
+  if (env.CHANNEL_PREFIXES !== undefined) {
+    input.channelPrefixes = env.CHANNEL_PREFIXES;
+  }
+  if (env.OPER_USER !== undefined || env.OPER_PASSWORD !== undefined) {
+    input.operCreds = [
+      {
+        user: env.OPER_USER ?? '',
+        password: env.OPER_PASSWORD ?? '',
+      },
+    ];
+  }
+  if (env.MAX_CHANNELS_PER_USER !== undefined) {
+    input.maxChannelsPerUser = Number.parseInt(env.MAX_CHANNELS_PER_USER, 10);
+  }
+  if (env.MAX_TARGETS_PER_COMMAND !== undefined) {
+    input.maxTargetsPerCommand = Number.parseInt(env.MAX_TARGETS_PER_COMMAND, 10);
+  }
+  if (env.NICK_LEN !== undefined) {
+    input.nickLen = Number.parseInt(env.NICK_LEN, 10);
+  }
+  if (env.CHANNEL_LEN !== undefined) {
+    input.channelLen = Number.parseInt(env.CHANNEL_LEN, 10);
+  }
+  if (env.TOPIC_LEN !== undefined) {
+    input.topicLen = Number.parseInt(env.TOPIC_LEN, 10);
+  }
+  if (env.MAX_LIST_ENTRIES !== undefined) {
+    input.maxListEntries = Number.parseInt(env.MAX_LIST_ENTRIES, 10);
+  }
+  if (env.QUIT_MESSAGE !== undefined) {
+    input.quitMessage = env.QUIT_MESSAGE;
+  }
+  if (env.SASL_ACCOUNTS !== undefined && env.SASL_ACCOUNTS.length > 0) {
+    input.saslAccounts = parseSaslAccountsLines(env.SASL_ACCOUNTS);
+  }
+  return input;
+}
+
+/**
+ * Parses a newline-delimited `username:password` string into the config's
+ * `saslAccounts` shape. Malformed entries (missing colon, empty fields)
+ * are skipped so a trailing newline or partial edit does not break boot.
+ */
+function parseSaslAccountsLines(raw: string): Array<{ username: string; password: string }> {
+  const out: Array<{ username: string; password: string }> = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue;
+    const username = trimmed.slice(0, sep);
+    const password = trimmed.slice(sep + 1);
+    if (username.length === 0 || password.length === 0) continue;
+    out.push({ username, password });
+  }
+  return out;
+}
+
+/**
+ * Loads and validates the server config from a Lambda env. Throws a
+ * readable `Error` listing every invalid field on failure.
+ */
+export function loadServerConfigFromLambdaEnv(env: LambdaConfigEnv): ParsedServerConfig {
+  return parseServerConfig(buildLambdaConfigInput(env));
+}

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

@@ -0,0 +1,156 @@
+/**
+ * DynamoDB-backed {@link AccountStore} primitives for the AWS adapter.
+ *
+ * The `Accounts` DynamoDB table stores SASL PLAIN credentials as
+ * **scrypt hashes** (never plaintext). Each row is a flat
+ * {@link HashedAccountCredential} (`{ account, algorithm, salt, hash }`).
+ *
+ * Two-phase construction keeps the `AccountStore` port synchronous:
+ *   1. {@link loadDynamoAccountStore} (async) scans the table at Lambda
+ *      cold start and returns a fully-populated `DynamoAccountStore`.
+ *   2. `DynamoAccountStore(entries)` (sync constructor) takes the
+ *      pre-loaded entries. The class itself has zero DynamoDB
+ *      coupling — it works equally well with entries from any source.
+ *
+ * This mirrors the pre-load pattern documented in
+ * `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.
+ */
+
+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;
+
+/**
+ * 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'),
+  };
+}
+
+/**
+ * Verifies a plaintext password against a {@link HashedAccountCredential}
+ * using `timingSafeEqual` (no short-circuit on first mismatched byte).
+ *
+ * Returns `false` for malformed entries rather than throwing — a corrupt
+ * row should not crash the SASL exchange.
+ */
+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;
+  }
+}
+
+/**
+ * Scans the `Accounts` table and returns a fully-populated
+ * {@link DynamoAccountStore}, or `undefined` when the table has no rows.
+ *
+ * Handles pagination (`LastEvaluatedKey`) so tables larger than the 1 MB
+ * scan page are fully loaded. Rows missing required attributes are
+ * silently skipped.
+ */
+export async function loadDynamoAccountStore(
+  docClient: DynamoDBDocumentClient,
+  tableName: string,
+): Promise<DynamoAccountStore | undefined> {
+  const entries: HashedAccountCredential[] = [];
+  let exclusiveStartKey: Record<string, unknown> | undefined = undefined;
+  do {
+    const result: ScanCommandOutput = await docClient.send(
+      new ScanCommand({
+        TableName: tableName,
+        ExclusiveStartKey: exclusiveStartKey,
+      }),
+    );
+    for (const item of result.Items ?? []) {
+      const account = typeof item.account === 'string' ? item.account : undefined;
+      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 });
+      }
+    }
+    exclusiveStartKey = result.LastEvaluatedKey;
+  } while (exclusiveStartKey !== undefined);
+  if (entries.length === 0) return undefined;
+  return new DynamoAccountStore(entries);
+}

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

@@ -0,0 +1,61 @@
+/**
+ * DynamoDB DocumentClient factory.
+ *
+ * Centralised so the runtime, the handlers, and the test harness all
+ * build their clients with the same marshalling conventions
+ * (`removeUndefinedValues: true`, native JS values in/out).
+ */
+
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import {
+  DynamoDBDocumentClient,
+  type TranslateConfig,
+  type marshallOptions,
+  type unmarshallOptions,
+} from '@aws-sdk/lib-dynamodb';
+
+/** Default marshalling options — every caller uses these. */
+const DEFAULT_TRANSLATE: TranslateConfig = {
+  marshallOptions: {
+    removeUndefinedValues: true,
+    convertClassInstanceToMap: false,
+  } as marshallOptions,
+  unmarshallOptions: {} as unmarshallOptions,
+};
+
+/**
+ * Builds a {@link DynamoDBDocumentClient} pointed at `endpoint`
+ * (or AWS proper when `endpoint` is omitted).
+ *
+ * Tests pass `endpoint` so they can address DynamoDB Local; production
+ * constructs the client with no endpoint and lets the SDK resolve the
+ * region from the Lambda execution role.
+ *
+ * `region` defaults to `'us-east-1'` when unset. DynamoDB Local ignores
+ * the value but the SDK requires one to be present so it can build the
+ * SigV4 signature. Production deployments inject a real region via the
+ * Lambda execution environment (`AWS_REGION`).
+ *
+ * When `endpoint` is supplied (the documented signal for DynamoDB Local
+ * / test mode) dummy static credentials are injected. The SDK v3 signs
+ * every request with SigV4 even against a local endpoint, so without
+ * credentials the default provider chain fails with
+ * `CredentialsProviderError`. Production never passes an endpoint and
+ * therefore resolves real credentials from the Lambda execution role.
+ */
+export function createDynamoDocumentClient(opts: {
+  endpoint?: string;
+  region?: string;
+}): DynamoDBDocumentClient {
+  const region = opts.region ?? process.env.AWS_REGION ?? 'us-east-1';
+  const client = new DynamoDBClient({
+    region,
+    ...(opts.endpoint !== undefined
+      ? {
+          endpoint: opts.endpoint,
+          credentials: { accessKeyId: 'local', secretAccessKey: 'local' },
+        }
+      : {}),
+  });
+  return DynamoDBDocumentClient.from(client, DEFAULT_TRANSLATE);
+}

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

@@ -0,0 +1,44 @@
+/**
+ * `$connect` handler — Lambda entry for `event.requestContext.routeKey === '$connect'`.
+ *
+ * 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.
+ */
+
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import type { ParsedServerConfig } from '@serverless-ircd/irc-core';
+import { marshalConnection } from '../serialize.js';
+import type { TablesConfig } from '../tables.js';
+import { createInitialConnectionState } from './state.js';
+
+/** Parameters accepted by {@link handleConnect}. */
+export interface ConnectParams {
+  dynamo: DynamoDBDocumentClient;
+  tables: TablesConfig;
+  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;
+}
+
+/**
+ * Inserts the Connections row for a fresh WebSocket upgrade.
+ *
+ * Idempotent: APIGW retries `$connect` on transient failures, so we
+ * use `PutCommand` (overwrites) rather than a conditional insert.
+ */
+export async function handleConnect(params: ConnectParams): Promise<void> {
+  const now = params.now ?? Date.now();
+  const state = createInitialConnectionState(params.connectionId, now);
+  void params.serverConfig; // reserved for max-clients gating (later ticket)
+  const row = marshalConnection(state, now);
+  await params.dynamo.send(
+    new PutCommand({
+      TableName: params.tables.Connections,
+      Item: row,
+    }),
+  );
+}