serverless-ircd 0.2.0 → 0.3.0

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

@@ -2,13 +2,15 @@
  * `$disconnect` handler — Lambda entry for `event.requestContext.routeKey === '$disconnect'`.
  *
  * Tears down the connection via {@link cleanupConnection} — deletes the
- * Connections row, every ChannelMembers row owned by it, and the nick
- * reservation if any. Idempotent: every step tolerates a missing row.
+ * Connections row, every ChannelMembers row owned by it, the nick
+ * reservation if any, and broadcasts a `QUIT` line to every peer sharing
+ * a channel with the disconnecting connection. Idempotent: every step
+ * tolerates a missing row.
  */
 
 import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { cleanupConnection } from '../aws-runtime.js';
+import { type PostToConnection, cleanupConnection } from '../aws-runtime.js';
 import type { TablesConfig } from '../tables.js';
 
 /** Parameters accepted by {@link handleDisconnect}. */
@@ -16,14 +18,31 @@ export interface DisconnectParams {
   dynamo: DynamoDBDocumentClient;
   tables: TablesConfig;
   connectionId: string;
-  /** Reserved for future "broadcast QUIT to peers" work; unused today. */
-  managementApi?: ApiGatewayManagementApi | null;
+  /**
+   * Backend used to push the `QUIT` fanout to peers. `null` skips the
+   * fanout (the socket is already gone, but peers still need the QUIT
+   * line so their rosters prune the ghost member).
+   */
+  managementApi?: ApiGatewayManagementApi | PostToConnection | null;
+  /**
+   * QUIT reason advertised to peers on fanout. Defaults to
+   * `'Client Quit'` (the same default the QUIT reducer uses when a
+   * client sends `QUIT` with no reason).
+   */
+  quitMessage?: string;
 }
 
 /**
- * Cleans up the connection state. Safe to call after APIGW has already
- * torn the WebSocket down — the management API is best-effort only.
+ * Cleans up the connection state and broadcasts QUIT to shared-channel
+ * peers. Safe to call after APIGW has already torn the WebSocket down —
+ * the management API is best-effort only.
  */
 export async function handleDisconnect(params: DisconnectParams): Promise<void> {
-  await cleanupConnection(params.dynamo, params.tables, params.connectionId, null);
+  await cleanupConnection(
+    params.dynamo,
+    params.tables,
+    params.connectionId,
+    params.managementApi ?? null,
+    params.quitMessage,
+  );
 }

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

@@ -14,12 +14,14 @@
 import { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import {
+  type AccountStore,
   EmptyMotdProvider,
   type MessageStore,
   type MotdProvider,
   type ParsedServerConfig,
   StaticMotdProvider,
 } from '@serverless-ircd/irc-core';
+import { resolveAccountStore } from '../account-store.js';
 import { type LambdaConfigEnv, loadServerConfigFromLambdaEnv } from '../config-loader.js';
 import { createDynamoDocumentClient } from '../dynamo.js';
 import { bindMessageStore } from '../message-store.js';
@@ -72,6 +74,13 @@ export interface HandlerDeps {
    * DynamoDB-backed variant is a documented follow-up.
    */
   messages: MessageStore;
+  /**
+   * SASL account verification source bound to every actor. Constructed
+   * once per cold start (memoised via {@link cachedDeps}) so it survives
+   * across warm Lambda invocations. `undefined` when no accounts are
+   * configured (the default) so `ctx.accounts` stays unset.
+   */
+  accounts?: AccountStore;
 }
 
 /**
@@ -90,6 +99,15 @@ export type DefaultEvent = {
 /** Memoised `HandlerDeps`; built on the first cold-start invocation. */
 let cachedDeps: HandlerDeps | undefined;
 
+/**
+ * In-flight cold-start build. `buildDepsFromEnv` is async (it scans the
+ * `Accounts` DynamoDB table for SASL credentials), so under concurrent
+ * warm-up two events could race past the `cachedDeps` check and each
+ * trigger a full scan. Memoising the promise guarantees the scan runs
+ * exactly once per cold start.
+ */
+let cachedDepsPromise: Promise<HandlerDeps> | undefined;
+
 /**
  * The Lambda entry point. Routes on `event.requestContext.routeKey`.
  *
@@ -98,7 +116,11 @@ let cachedDeps: HandlerDeps | undefined;
  */
 export const handler = async (event: WebSocketEvent): Promise<LambdaResponse> => {
   if (cachedDeps === undefined) {
-    cachedDeps = buildDepsFromEnv();
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
   }
   const deps = cachedDeps;
   return dispatch(event, deps);
@@ -125,6 +147,7 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
         tables: deps.tables,
         connectionId: connId,
         managementApi: deps.managementApi,
+        quitMessage: deps.serverConfig.quitMessage,
       });
       return { statusCode: 200 };
 
@@ -141,6 +164,7 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
           serverConfig: deps.serverConfig,
           motd: deps.motd,
           messages: deps.messages,
+          ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
           managementApi: deps.managementApi,
         });
         return result;
@@ -159,6 +183,7 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
  */
 export function __resetHandlerCacheForTests(): void {
   cachedDeps = undefined;
+  cachedDepsPromise = undefined;
 }
 
 /**
@@ -172,7 +197,11 @@ export function __resetHandlerCacheForTests(): void {
  */
 export async function sweeperHandler(_event: unknown): Promise<SweepResult> {
   if (cachedDeps === undefined) {
-    cachedDeps = buildDepsFromEnv();
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
   }
   const deps = cachedDeps;
   return handleSweep({ dynamo: deps.dynamo, tables: deps.tables });
@@ -190,7 +219,11 @@ export async function sweeperHandler(_event: unknown): Promise<SweepResult> {
  */
 export async function pingCheckerHandler(_event: unknown): Promise<PingCheckResult> {
   if (cachedDeps === undefined) {
-    cachedDeps = buildDepsFromEnv();
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
   }
   const deps = cachedDeps;
   return handlePingCheck({
@@ -216,9 +249,12 @@ export {
  * Builds a {@link HandlerDeps} from the current `process.env`.
  *
  * Exposed so tests can construct production-shaped deps without re-running
- * the env parsing.
+ * the env parsing. Async because it scans the `Accounts` DynamoDB table
+ * (via {@link resolveAccountStore}) to pre-load SASL credentials at cold
+ * start — the {@link AccountStore} port is synchronous, so the scan must
+ * complete before any reducer calls `verify`.
  */
-export function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): HandlerDeps {
+export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Promise<HandlerDeps> {
   const cfg = loadServerConfigFromLambdaEnv(env as LambdaConfigEnv);
   const tables = tablesConfigFromEnv(env);
   const region = typeof env.AWS_REGION === 'string' ? env.AWS_REGION : undefined;
@@ -231,7 +267,16 @@ export function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): HandlerD
   }
   const motd = cfg.motdLines.length > 0 ? new StaticMotdProvider(cfg.motdLines) : EmptyMotdProvider;
   const messages = bindMessageStore(cfg);
-  return { dynamo, tables, serverConfig: cfg, motd, managementApi, messages };
+  const accounts = await resolveAccountStore(dynamo, tables.Accounts, cfg);
+  return {
+    dynamo,
+    tables,
+    serverConfig: cfg,
+    motd,
+    managementApi,
+    messages,
+    ...(accounts !== undefined ? { accounts } : {}),
+  };
 }
 
 function tablesConfigFromEnv(env: NodeJS.ProcessEnv): TablesConfig {

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

@@ -16,6 +16,13 @@ export { cleanupConnection } from './aws-runtime.js';
 export { TABLE_KEYS, TABLE_NAMES, tablesConfigFromNames } from './tables.js';
 export type { TableName, TablesConfig } from './tables.js';
 export { createDynamoDocumentClient } from './dynamo.js';
+export {
+  DynamoAccountStore,
+  type HashedAccountCredential,
+  hashAccountCredential,
+  loadDynamoAccountStore,
+} from './dynamo-account-store.js';
+export { bindAccountStore, putAccountCredential, resolveAccountStore } from './account-store.js';
 export {
   loadServerConfigFromLambdaEnv,
   type LambdaConfigEnv,

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

@@ -0,0 +1,171 @@
+/**
+ * DynamoDB-backed integration tests for the `Accounts` table path.
+ * Exercises the real DynamoDB round-trip that pure unit
+ * tests cannot: `putAccountCredential` writes a hashed row,
+ * `loadDynamoAccountStore` scans it back, and `resolveAccountStore`
+ * applies the table-then-config precedence.
+ *
+ * Gated on DynamoDB Local availability (same `DDB_AVAILABLE` flag as
+ * `handlers.test.ts`).
+ */
+
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import { DEFAULT_SERVER_CONFIG } from '@serverless-ircd/irc-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  loadDynamoAccountStore,
+  putAccountCredential,
+  resolveAccountStore,
+} from '../src/account-store.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+
+const available = process.env.DDB_AVAILABLE === '1';
+const endpoint = process.env.DYNAMO_ENDPOINT;
+
+interface Fx {
+  tableName: string;
+  client: ReturnType<typeof createDynamoDocumentClient>;
+  cleanup: () => Promise<void>;
+}
+
+let fx: Fx | null = null;
+
+async function makeFx(): Promise<Fx> {
+  if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
+  const tableName = `acct-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+  const client = createDynamoDocumentClient({ endpoint });
+  const props = TABLE_DEFS.Accounts;
+  const pkName = props.partitionKey?.name;
+  if (pkName === undefined) throw new Error('Accounts table missing partitionKey');
+  await client.send(
+    new CreateTableCommand({
+      TableName: tableName,
+      AttributeDefinitions: [{ AttributeName: pkName, AttributeType: 'S' }],
+      KeySchema: [{ AttributeName: pkName, KeyType: 'HASH' }],
+      BillingMode: 'PAY_PER_REQUEST',
+    }),
+  );
+  return {
+    tableName,
+    client,
+    cleanup: async () => {
+      try {
+        await client.send(new DeleteTableCommand({ TableName: tableName }));
+      } catch {
+        // Idempotent.
+      }
+    },
+  };
+}
+
+describe.skipIf(!available)('Accounts table round-trip', () => {
+  beforeEach(async () => {
+    fx = await makeFx();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('putAccountCredential then loadDynamoAccountStore verifies the account', async () => {
+    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 's3cret');
+    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    expect(store).toBeDefined();
+    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 's3cret' })).toEqual(
+      {
+        ok: true,
+        account: 'alice',
+      },
+    );
+  });
+
+  it('loadDynamoAccountStore returns undefined when the table has no rows', async () => {
+    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    expect(store).toBeUndefined();
+  });
+
+  it('putAccountCredential writes multiple distinct accounts', async () => {
+    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'a1');
+    await putAccountCredential(fx!.client, fx!.tableName, 'bob', 'b2');
+    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    expect(store).toBeDefined();
+    expect(store!.size).toBe(2);
+    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'a1' }).ok).toBe(
+      true,
+    );
+    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'bob', password: 'b2' }).ok).toBe(true);
+  });
+
+  it('putAccountCredential overwrites an existing account (re-seed)', async () => {
+    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'old');
+    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'new');
+    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    expect(store).toBeDefined();
+    expect(store!.size).toBe(1);
+    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'old' }).ok).toBe(
+      false,
+    );
+    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'new' }).ok).toBe(
+      true,
+    );
+  });
+
+  it('rejects a wrong password after round-trip', async () => {
+    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'right');
+    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    expect(store).toBeDefined();
+    expect(
+      store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'wrong' }).ok,
+    ).toBe(false);
+  });
+});
+
+describe.skipIf(!available)('resolveAccountStore precedence', () => {
+  beforeEach(async () => {
+    fx = await makeFx();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('returns a DynamoAccountStore when the table has rows (table wins)', async () => {
+    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'table-secret');
+    const cfgWithSasl = {
+      ...DEFAULT_SERVER_CONFIG,
+      saslAccounts: [{ username: 'envuser', password: 'env-secret' }],
+    };
+    const store = await resolveAccountStore(fx!.client, fx!.tableName, cfgWithSasl);
+    expect(store).toBeDefined();
+    // Table account verifies; config account does NOT (table is authoritative).
+    expect(
+      store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'table-secret' }).ok,
+    ).toBe(true);
+    expect(
+      store!.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
+    ).toBe(false);
+  });
+
+  it('falls back to the config-seeded store when the table is empty', async () => {
+    const cfgWithSasl = {
+      ...DEFAULT_SERVER_CONFIG,
+      saslAccounts: [{ username: 'envuser', password: 'env-secret' }],
+    };
+    const store = await resolveAccountStore(fx!.client, fx!.tableName, cfgWithSasl);
+    expect(store).toBeDefined();
+    expect(
+      store!.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
+    ).toBe(true);
+  });
+
+  it('returns undefined when the table is empty and no config accounts are set', async () => {
+    const store = await resolveAccountStore(fx!.client, fx!.tableName, DEFAULT_SERVER_CONFIG);
+    expect(store).toBeUndefined();
+  });
+
+  it('returns undefined when the table is empty and serverConfig is undefined', async () => {
+    const store = await resolveAccountStore(fx!.client, fx!.tableName, undefined);
+    expect(store).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,280 @@
+import { mockClient } from 'aws-sdk-client-mock';
+import { DynamoDBDocumentClient, PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { type SaslPayload, DEFAULT_SERVER_CONFIG, type ParsedServerConfig } from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import {
+  DynamoAccountStore,
+  bindAccountStore,
+  hashAccountCredential,
+  type HashedAccountCredential,
+  putAccountCredential,
+  resolveAccountStore,
+} from '../src/account-store';
+
+function plainPayload(username: string, password: string): SaslPayload {
+  return { kind: 'PLAIN', username, password };
+}
+
+/** Builds a minimal parsed config with the supplied saslAccounts. */
+function configWith(accounts: Array<{ username: string; password: string }>): ParsedServerConfig {
+  return { ...DEFAULT_SERVER_CONFIG, saslAccounts: accounts };
+}
+
+// ---------------------------------------------------------------------------
+// bindAccountStore — config-seeded fallback
+// ---------------------------------------------------------------------------
+
+describe('bindAccountStore', () => {
+  it('returns an AccountStore that accepts valid PLAIN creds', () => {
+    const store = bindAccountStore(configWith([{ username: 'alice', password: 'secret' }]));
+    expect(store).toBeDefined();
+    const out = store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'secret' });
+    expect(out).toEqual({ ok: true, account: 'alice' });
+  });
+
+  it('returns undefined when the account list is empty', () => {
+    expect(bindAccountStore(configWith([]))).toBeUndefined();
+  });
+
+  it('returns undefined when serverConfig is undefined', () => {
+    expect(bindAccountStore(undefined)).toBeUndefined();
+  });
+
+  it('rejects wrong credentials', () => {
+    const store = bindAccountStore(configWith([{ username: 'alice', password: 'secret' }]))!;
+    expect(store.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'wrong' }).ok).toBe(
+      false,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// hashAccountCredential — pure scrypt hashing helper
+// ---------------------------------------------------------------------------
+
+describe('hashAccountCredential', () => {
+  it('produces an entry keyed by the username with scrypt', () => {
+    const entry = hashAccountCredential('alice', 'secret');
+    expect(entry.account).toBe('alice');
+    expect(entry.algorithm).toBe('scrypt');
+    expect(entry.salt.length).toBeGreaterThan(0);
+    expect(entry.hash.length).toBeGreaterThan(0);
+  });
+
+  it('never stores the plaintext password in any field', () => {
+    const entry = hashAccountCredential('alice', 'hunter2-secret');
+    expect(entry.account).not.toContain('hunter2');
+    expect(entry.salt).not.toContain('hunter2');
+    expect(entry.hash).not.toContain('hunter2');
+  });
+
+  it('produces different hashes for the same password under different salts', () => {
+    const a = hashAccountCredential('alice', 'secret', { salt: Buffer.from('aaaaaaaaaaaaaaaa') });
+    const b = hashAccountCredential('alice', 'secret', { salt: Buffer.from('bbbbbbbbbbbbbbbb') });
+    expect(a.hash).not.toBe(b.hash);
+  });
+
+  it('is deterministic for a fixed salt', () => {
+    const salt = Buffer.from('1234567890123456');
+    const a = hashAccountCredential('alice', 'secret', { salt });
+    const b = hashAccountCredential('alice', 'secret', { salt });
+    expect(a.hash).toBe(b.hash);
+  });
+
+  it('honours a custom key length', () => {
+    const entry = hashAccountCredential('alice', 'secret', { keyLen: 32 });
+    // base64 of 32 bytes → ~44 chars; base64 of 64 bytes → ~88 chars
+    expect(Buffer.from(entry.hash, 'base64').length).toBe(32);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DynamoAccountStore — synchronous verify against pre-loaded hashed entries
+// ---------------------------------------------------------------------------
+
+describe('DynamoAccountStore', () => {
+  it('accepts valid PLAIN credentials and returns the account name', () => {
+    const entry = hashAccountCredential('alice', 'secret');
+    const store = new DynamoAccountStore([entry]);
+    expect(store.verify('PLAIN', plainPayload('alice', 'secret'))).toEqual({
+      ok: true,
+      account: 'alice',
+    });
+  });
+
+  it('rejects a wrong password', () => {
+    const entry = hashAccountCredential('alice', 'secret');
+    const store = new DynamoAccountStore([entry]);
+    expect(store.verify('PLAIN', plainPayload('alice', 'wrong')).ok).toBe(false);
+  });
+
+  it('rejects an unknown username', () => {
+    const store = new DynamoAccountStore([hashAccountCredential('alice', 'secret')]);
+    expect(store.verify('PLAIN', plainPayload('bob', 'secret')).ok).toBe(false);
+  });
+
+  it('rejects a non-PLAIN mechanism', () => {
+    const store = new DynamoAccountStore([hashAccountCredential('alice', 'secret')]);
+    expect(store.verify('EXTERNAL', plainPayload('alice', 'secret')).ok).toBe(false);
+  });
+
+  it('rejects a RAW payload', () => {
+    const store = new DynamoAccountStore([hashAccountCredential('alice', 'secret')]);
+    expect(store.verify('PLAIN', { kind: 'RAW', data: 'whatever' }).ok).toBe(false);
+  });
+
+  it('handles multiple loaded accounts', () => {
+    const store = new DynamoAccountStore([
+      hashAccountCredential('alice', 'a-secret'),
+      hashAccountCredential('bob', 'b-secret'),
+    ]);
+    expect(store.verify('PLAIN', plainPayload('alice', 'a-secret'))).toEqual({
+      ok: true,
+      account: 'alice',
+    });
+    expect(store.verify('PLAIN', plainPayload('bob', 'b-secret'))).toEqual({
+      ok: true,
+      account: 'bob',
+    });
+  });
+
+  it('fails every verify when constructed with no entries', () => {
+    const store = new DynamoAccountStore([]);
+    expect(store.verify('PLAIN', plainPayload('alice', 'secret')).ok).toBe(false);
+  });
+
+  it('round-trips an externally-constructed HashedAccountCredential', () => {
+    const row: HashedAccountCredential = hashAccountCredential('carol', 'p@ss');
+    const store = new DynamoAccountStore([row]);
+    expect(store.verify('PLAIN', plainPayload('carol', 'p@ss'))).toEqual({
+      ok: true,
+      account: 'carol',
+    });
+  });
+
+  it('reports the number of loaded entries via size', () => {
+    const store = new DynamoAccountStore([
+      hashAccountCredential('alice', 'a'),
+      hashAccountCredential('bob', 'b'),
+    ]);
+    expect(store.size).toBe(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveAccountStore — table-then-config precedence (mock-based)
+// ---------------------------------------------------------------------------
+
+describe('resolveAccountStore', () => {
+  it('returns a DynamoAccountStore when the table has rows (table wins)', async () => {
+    const entry = hashAccountCredential('alice', 's3cret');
+    const ddb = mockClient(DynamoDBDocumentClient);
+    ddb.on(ScanCommand).resolves({
+      Items: [entry],
+    });
+
+    const fallback = bindAccountStore(configWith([{ username: 'envuser', password: 'env-pw' }]));
+    const store = await resolveAccountStore(
+      ddb as unknown as DynamoDBDocumentClient,
+      'Accounts',
+      fallback === undefined ? undefined : { ...DEFAULT_SERVER_CONFIG, saslAccounts: [{ username: 'envuser', password: 'env-pw' }] },
+    );
+    expect(store).toBeDefined();
+    expect(
+      store!.verify('PLAIN', plainPayload('alice', 's3cret')).ok,
+    ).toBe(true);
+    // Config account does NOT verify (table is authoritative).
+    expect(
+      store!.verify('PLAIN', plainPayload('envuser', 'env-pw')).ok,
+    ).toBe(false);
+  });
+
+  it('falls back to config-seeded store when the table is empty', async () => {
+    const ddb = mockClient(DynamoDBDocumentClient);
+    ddb.on(ScanCommand).resolves({ Items: [] });
+
+    const store = await resolveAccountStore(
+      ddb as unknown as DynamoDBDocumentClient,
+      'Accounts',
+      configWith([{ username: 'bob', password: 'pw' }]),
+    );
+    expect(store).toBeDefined();
+    expect(
+      store!.verify('PLAIN', plainPayload('bob', 'pw')).ok,
+    ).toBe(true);
+  });
+
+  it('falls back to config-seeded store when the scan throws', async () => {
+    const ddb = mockClient(DynamoDBDocumentClient);
+    ddb.on(ScanCommand).rejects(new Error('ResourceNotFoundException'));
+
+    const store = await resolveAccountStore(
+      ddb as unknown as DynamoDBDocumentClient,
+      'Accounts',
+      configWith([{ username: 'bob', password: 'pw' }]),
+    );
+    expect(store).toBeDefined();
+    expect(
+      store!.verify('PLAIN', plainPayload('bob', 'pw')).ok,
+    ).toBe(true);
+  });
+
+  it('returns undefined when table is empty and no config accounts', async () => {
+    const ddb = mockClient(DynamoDBDocumentClient);
+    ddb.on(ScanCommand).resolves({ Items: [] });
+
+    const store = await resolveAccountStore(
+      ddb as unknown as DynamoDBDocumentClient,
+      'Accounts',
+      undefined,
+    );
+    expect(store).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// putAccountCredential — CRUD/seed entry point (mock-based)
+// ---------------------------------------------------------------------------
+
+describe('putAccountCredential', () => {
+  it('writes a hashed row to DynamoDB and returns the credential', async () => {
+    const ddb = mockClient(DynamoDBDocumentClient);
+    ddb.on(PutCommand).resolves({});
+
+    const entry = await putAccountCredential(
+      ddb as unknown as DynamoDBDocumentClient,
+      'Accounts',
+      'alice',
+      's3cret',
+    );
+    expect(entry.account).toBe('alice');
+    expect(entry.algorithm).toBe('scrypt');
+
+    const calls = ddb.commandCalls(PutCommand);
+    expect(calls).toHaveLength(1);
+    const item = calls[0]!.args[0].input.Item as HashedAccountCredential;
+    expect(item.account).toBe('alice');
+    expect(item.algorithm).toBe('scrypt');
+    expect(item.salt).toBe(entry.salt);
+    expect(item.hash).toBe(entry.hash);
+  });
+
+  it('the written row round-trips through DynamoAccountStore', async () => {
+    const ddb = mockClient(DynamoDBDocumentClient);
+    ddb.on(PutCommand).resolves({});
+
+    const entry = await putAccountCredential(
+      ddb as unknown as DynamoDBDocumentClient,
+      'Accounts',
+      'alice',
+      's3cret',
+    );
+
+    // Simulate reading the row back via DynamoAccountStore.
+    const store = new DynamoAccountStore([entry]);
+    expect(store.verify('PLAIN', plainPayload('alice', 's3cret'))).toEqual({
+      ok: true,
+      account: 'alice',
+    });
+  });
+});