serverless-ircd 0.1.0 → 0.3.0

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

@@ -0,0 +1,121 @@
+/**
+ * SASL account store construction + resolution for the AWS adapter.
+ *
+ * Centralises `AccountStore` creation so the actor-construction site
+ * (`handleDefault`) binds a single helper rather than constructing the
+ * store inline. Two sources of credentials are reconciled here:
+ *
+ *   1. The DynamoDB `Accounts` table (authoritative when populated) —
+ *      loaded at cold start into a {@link DynamoAccountStore} by
+ *      {@link resolveAccountStore}. Credentials are stored as scrypt
+ *      hashes, never plaintext.
+ *   2. The parsed server config (`saslAccounts`, sourced from the
+ *      `SASL_ACCOUNTS` env var) — the legacy/config fallback used only
+ *      when the table is empty, preserving the config-seed behaviour for
+ *      deployments that have not migrated to the table.
+ *
+ * The resolved store is scoped to the Lambda execution context: it
+ * persists across warm invocations (via the memoised `HandlerDeps`) but
+ * is rebuilt on cold start, picking up account changes made since the
+ * last cold start.
+ */
+
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import {
+  type AccountStore,
+  InMemoryAccountStore,
+  type ParsedServerConfig,
+} from '@serverless-ircd/irc-core';
+import {
+  type HashedAccountCredential,
+  DynamoAccountStore,
+  hashAccountCredential,
+  loadDynamoAccountStore,
+} from './dynamo-account-store.js';
+
+// Re-export so callers can import everything from one module.
+export {
+  DynamoAccountStore,
+  type HashedAccountCredential,
+  hashAccountCredential,
+  loadDynamoAccountStore,
+};
+
+/**
+ * Constructs the config-seeded in-memory account store (the legacy
+ * fallback). Returns `undefined` when no accounts are configured so the
+ * actor's `ctx.accounts` stays unset (preserving the no-store behaviour:
+ * `AUTHENTICATE PLAIN` → `904`).
+ *
+ * @param serverConfig Parsed config carrying the `saslAccounts` seed list.
+ */
+export function bindAccountStore(serverConfig?: ParsedServerConfig): AccountStore | undefined {
+  if (serverConfig === undefined || serverConfig.saslAccounts.length === 0) {
+    return undefined;
+  }
+  return new InMemoryAccountStore(serverConfig.saslAccounts);
+}
+
+/**
+ * Resolves the SASL account store for a deployment, applying the
+ * table-then-config precedence.
+ *
+ *   1. Scans the DynamoDB `Accounts` table (pre-loading every hashed
+ *      credential into a {@link DynamoAccountStore}). When the table has
+ *      one or more rows it is authoritative — the table wins and the
+ *      config seed is ignored.
+ *   2. When the table is empty, falls back to {@link bindAccountStore}
+ *      (the `SASL_ACCOUNTS` env-var seed) so existing deployments that
+ *      have not migrated to the table keep working unchanged.
+ *   3. Returns `undefined` when neither source has accounts (the default)
+ *      so `ctx.accounts` stays unset and `AUTHENTICATE PLAIN` → `904`.
+ *
+ * Scan failures (table not found, network error) are swallowed and
+ * treated as an empty table, falling through to the config seed.
+ *
+ * @param docClient DynamoDB client addressed at the deployment's tables.
+ * @param tableName Physical name of the `Accounts` table for this env.
+ * @param serverConfig Parsed config (the config-seed fallback source).
+ */
+export async function resolveAccountStore(
+  docClient: DynamoDBDocumentClient,
+  tableName: string,
+  serverConfig?: ParsedServerConfig,
+): Promise<AccountStore | undefined> {
+  try {
+    const store = await loadDynamoAccountStore(docClient, tableName);
+    if (store !== undefined) return store;
+  } catch {
+    // Table might not exist or be unreachable; fall through to config seed.
+  }
+  return bindAccountStore(serverConfig);
+}
+
+/**
+ * Writes (or re-seeds) a SASL PLAIN account into the `Accounts` table.
+ *
+ * The password is hashed via {@link hashAccountCredential} (scrypt,
+ * random salt) and stored as a {@link HashedAccountCredential} row —
+ * plaintext is never written. A repeat call for the same `username`
+ * overwrites the prior row (the PK is `account`), so this is the
+ * canonical CRUD/seed entry point for oper and SASL account
+ * provisioning.
+ *
+ * @returns The stored {@link HashedAccountCredential} (for tooling/tests).
+ */
+export async function putAccountCredential(
+  docClient: DynamoDBDocumentClient,
+  tableName: string,
+  username: string,
+  password: string,
+): Promise<HashedAccountCredential> {
+  const entry = hashAccountCredential(username, password);
+  await docClient.send(
+    new PutCommand({
+      TableName: tableName,
+      Item: entry,
+    }),
+  );
+  return entry;
+}