serverless-ircd 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-ircd",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "private": false,
   "description": "Serverless IRC daemon with a platform-agnostic core and Cloudflare Workers + AWS adapters",
   "license": "BSD-3-Clause",
@@ -17,7 +17,7 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
     "vitest": "^4.1.10",
-    "@serverless-ircd/aws-adapter": "0.8.0"
+    "@serverless-ircd/aws-adapter": "0.10.0"
   },
   "scripts": {
     "build": "turbo run build",
@@ -32,13 +32,10 @@
     "mutation:commands": "pnpm --filter @serverless-ircd/irc-core mutation:commands",
     "mutation": "pnpm run mutation:protocol && pnpm run mutation:commands",
     "clean": "turbo run clean && rimraf node_modules",
-    "deploy:cf:staging": "pnpm --filter @serverless-ircd/cf-worker deploy:staging",
-    "deploy:cf:prod": "pnpm --filter @serverless-ircd/cf-worker deploy:prod",
-    "smoke:cf:staging": "pnpm --filter @serverless-ircd/cf-worker smoke:staging",
-    "deploy:cf-tcp:staging": "pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container deploy:staging",
-    "deploy:cf-tcp:prod": "pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container deploy:prod",
-    "deploy:aws:staging": "pnpm build && pnpm --filter @serverless-ircd/aws-stack deploy:staging",
-    "deploy:aws:prod": "pnpm build && pnpm --filter @serverless-ircd/aws-stack deploy:prod",
-    "smoke:aws:staging": "pnpm --filter @serverless-ircd/aws-stack smoke:staging"
+    "deploy:cf": "pnpm --filter @serverless-ircd/cf-worker run deploy",
+    "smoke:cf": "pnpm --filter @serverless-ircd/cf-worker run smoke",
+    "deploy:cf-tcp": "pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container run deploy",
+    "deploy:aws": "pnpm build && pnpm --filter @serverless-ircd/aws-stack run deploy",
+    "smoke:aws": "pnpm --filter @serverless-ircd/aws-stack run smoke"
   }
 }

package/packages/aws-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-adapter",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "private": true,
   "description": "AWS Lambda + DynamoDB adapter: AwsRuntime implementing IrcRuntime + $connect/$disconnect/$default handlers",
   "license": "BSD-3-Clause",

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

@@ -459,10 +459,15 @@ export class AwsRuntime implements IrcRuntime {
   // -------------------------------------------------------------------------
 
   private async readConnectionRow(conn: ConnId): Promise<MarshalledConnection | null> {
+    // Strongly consistent: peer lookups (WHOIS, roster hydration) read a
+    // row that may have just been written by another frame. An eventually-
+    // consistent Get could present a stale peer snapshot under replication
+    // lag.
     const result = await this.dynamo.send(
       new GetCommand({
         TableName: this.tables.Connections,
         Key: { connectionId: conn },
+        ConsistentRead: true,
       }),
     );
     if (result.Item === undefined) return null;
@@ -723,7 +728,16 @@ export async function cleanupConnection(
   quitMessage = 'Client Quit',
 ): Promise<void> {
   const connRow = await dynamo.send(
-    new GetCommand({ TableName: tables.Connections, Key: { connectionId: connId } }),
+    // Strongly consistent: $disconnect (and the send()/broadcast()
+    // GoneException path) can fire on the very next frame after the
+    // connection's own row was last written/updated. An eventually-
+    // consistent Get can miss that just-written row under DynamoDB
+    // replication lag and skip nick release + roster fanout.
+    new GetCommand({
+      TableName: tables.Connections,
+      Key: { connectionId: connId },
+      ConsistentRead: true,
+    }),
   );
   const item = connRow.Item as unknown as MarshalledConnection | undefined;
   if (item === undefined) return; // idempotent — already cleaned up

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

@@ -18,11 +18,11 @@
  *     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.
  */
@@ -32,7 +32,7 @@ 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
+ * 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
@@ -65,11 +65,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

@@ -53,10 +53,27 @@ 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;
 }
 
 /**

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

@@ -198,6 +198,7 @@ export class DynamoServicesStore extends PersistentServicesStore {
       email: row.email,
       createdAt: row.createdAt,
       enforce: row.enforce,
+      certSubjects: row.certSubjects ?? [],
       algorithm: row.credential.algorithm,
       salt: row.credential.salt,
       hash: row.credential.hash,
@@ -536,12 +537,18 @@ 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')
+    : [];
   return {
     nick: item.nick,
     account: item.account,
     email: item.email,
     createdAt: item.createdAt,
     enforce: item.enforce as NickEnforcePolicy,
+    certSubjects,
     credential: {
       account: item.account,
       algorithm: 'scrypt',

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

@@ -24,6 +24,7 @@ import {
 } from '@serverless-ircd/irc-core';
 import { type AdmissionOutcome, decideConnectAdmission } from '../admission.js';
 import { decrementConnectionCount, incrementConnectionCount } from '../connection-counter.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 +45,22 @@ 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;
 }
 
 /**
@@ -83,6 +100,15 @@ 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' };
+  }
+
   // 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.

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

@@ -12,7 +12,6 @@ import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanageme
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import { GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import {
-  type AccountStore,
   type ChannelState,
   type Clock,
   type ConnectionState,
@@ -63,19 +62,14 @@ export interface DefaultParams {
    * behaviour of callers that have not opted in.
    */
   messages?: MessageStore;
-  /**
-   * SASL account verification source. When omitted the actor runs with
-   * `ctx.accounts` undefined so `AUTHENTICATE PLAIN` fails with `904`
-   * — preserves the behaviour of callers that have not opted in.
-   */
-  accounts?: AccountStore;
   /**
    * Persistent services store (NickServ / ChanServ / HostServ / MemoServ /
-   * OperServ + read-marker). When omitted the actor runs with
-   * `ctx.services` undefined so `PRIVMSG NickServ` / ChanServ routing is
-   * disabled — preserves the behaviour of callers that have not opted in.
-   * On success the handler flushes pending write-behind ops after the
-   * actor run.
+   * OperServ + read-marker + the unified SASL/PASS credential home). When
+   * omitted the actor runs with `ctx.services` undefined so
+   * `PRIVMSG NickServ` / ChanServ routing is disabled and every SASL/PASS
+   * credential verify fails — preserves the behaviour of callers that
+   * have not opted in. On success the handler flushes pending
+   * write-behind ops after the actor run.
    */
   services?: DynamoServicesStore;
   /**
@@ -128,113 +122,144 @@ export interface DefaultParams {
 export async function handleDefault(params: DefaultParams): Promise<{ statusCode: number }> {
   const clock = params.clock ?? SystemClock;
   const ids = params.ids ?? new UuidIdFactory();
-  // Load persisted state. Strongly consistent: $connect writes this row and
-  // $default reads it on the very next frame — an eventually-consistent Get
-  // can miss the just-written row (DynamoDB replication lag) and silently
-  // drop the client's first frame as a 410. Strong consistency closes that
-  // read-after-write window.
-  const result = await params.dynamo.send(
-    new GetCommand({
-      TableName: params.tables.Connections,
-      Key: { connectionId: params.connectionId },
-      ConsistentRead: true,
-    }),
-  );
-  if (result.Item === undefined) {
-    // Previously this branch returned silently, making a missing-row
-    // $default invisible to operators (client sees nothing, logs show
-    // nothing). Warn so the 410 path is diagnosable.
-    console.warn(
-      `[irc-handler] $default connId=${params.connectionId} wsMode=? row=missing -> 410`,
-    );
-    return { statusCode: 410 };
-  }
-  const persisted = result.Item as unknown as MarshalledConnection;
-  const state = unmarshalConnection(persisted);
-
-  // Recover the IRCv3 WebSocket frame mode persisted at `$connect`.
-  // Absent = legacy (no subprotocol negotiated). Drives both the inbound
-  // line-framing transport (spec: one IRC message per frame, never split)
-  // and the outbound delivery shape (spec: one postToConnection per line).
-  const wsMode: WsFrameMode = persisted.wsMode ?? 'legacy';
-
-  // Mark this frame's activity.
-  state.lastSeen = clock.now();
 
-  // Build the runtime + handlers.
+  // Optimistic-concurrency retry loop. API Gateway dispatches a client's
+  // rapid frames (CAP END, NICK, USER; or two PRIVMSG) as CONCURRENT
+  // Lambda invocations that each read-modify-write the same Connections
+  // row. Each attempt:
+  //   1. Strongly-consistent read (closes the $connect→$default window).
+  //   2. Run the actor over the frame against the fresh state.
+  //   3. Conditional write requiring `revision = :expected`; on conflict
+  //      (another invocation wrote first) re-read and re-run.
+  // Membership writes (TransactWriteItems + ADD/DELETE on a String Set)
+  // are idempotent by design, so a retried frame never doubles roster
+  // state. NOTE: peer `postToConnection` calls issued inside the actor
+  // run MAY double-deliver on the rare retry; registration (the deadlock
+  // this fixes) has no peer sends, and a duplicated PRIVMSG on a rare
+  // retry is strictly better than the total state-loss this loop fixes.
+  // Full peer-send buffering is a documented follow-up.
+  const MAX_RETRIES = 8;
   const outbound: string[] = [];
-  const handlers: AwsRuntimeHandlers = {
-    send: (lines) => {
-      // Self-send: APIGW echoes back to the caller's open socket via the
-      // management API in production; in tests we collect for assertions.
-      for (const l of lines) outbound.push(l.text);
-    },
-    disconnect: () => {
-      // No-op: a Lambda `$default` invocation cannot close its own APIGW
-      // socket. The canonical teardown is the `$disconnect` route (which
-      // fires when APIGW observes the close) plus the sweeper/ping-checker
-      // for connections that vanish without one. The actor's state
-      // mutations (nick release, roster deltas) are persisted below before
-      // this invocation returns, so the eventual `$disconnect` completes
-      // the fanout. See docs/AWS-Deployment.md §14.1.
-    },
-    snapshot: () => state,
-  };
-  const runtime = new AwsRuntime({
-    dynamo: params.dynamo,
-    tables: params.tables,
-    connId: params.connectionId,
-    handlers,
-    managementApi: params.managementApi,
-    clock,
-    ...(params.configLoader !== undefined ? { configLoader: params.configLoader } : {}),
-  });
-
-  const channelAccess = new LambdaChannelAccess(runtime, clock.now());
+  // Captured from the committed attempt so the post-loop outbound flush
+  // knows the connection's frame mode (spec vs legacy line framing).
+  let wsModeHolder: WsFrameMode = 'legacy';
 
-  const actor = new ConnectionActor({
-    state,
-    runtime,
-    channels: channelAccess,
-    serverConfig: params.serverConfig,
-    configSource: 'Secrets Manager',
-    clock,
-    ids,
-    motd: params.motd,
-    transport: { feed: (chunk) => frameToLines(chunk, wsMode) },
-    // AwsStats Scans Connections + ChannelMeta for LUSERS/STATS.
-    // `uptimeStartedAt` is captured at the Lambda's cold start so `STATS u`
-    // reports per-isolate uptime; a deployment-wide uptime would require a
-    // persistent record (future work).
-    stats: new AwsStats({
+  /** Builds a fresh actor for `state` and runs this invocation's frame. */
+  const runFrame = async (state: ConnectionState, wsMode: WsFrameMode): Promise<void> => {
+    const handlers: AwsRuntimeHandlers = {
+      send: (lines) => {
+        // Self-send: APIGW echoes back to the caller's open socket via the
+        // management API in production; in tests we collect for assertions.
+        for (const l of lines) outbound.push(l.text);
+      },
+      disconnect: () => {
+        // No-op: a Lambda `$default` invocation cannot close its own APIGW
+        // socket. The canonical teardown is the `$disconnect` route (which
+        // fires when APIGW observes the close) plus the sweeper/ping-checker
+        // for connections that vanish without one. The actor's state
+        // mutations (nick release, roster deltas) are persisted below before
+        // this invocation returns, so the eventual `$disconnect` completes
+        // the fanout. See docs/AWS-Deployment.md §14.1.
+      },
+      snapshot: () => state,
+    };
+    const runtime = new AwsRuntime({
       dynamo: params.dynamo,
       tables: params.tables,
-      uptimeStartedAt: LAMBDA_STARTUP_AT,
-    }),
-    ...(params.messages !== undefined ? { messages: params.messages } : {}),
-    ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
-    ...(params.services !== undefined ? { services: params.services } : {}),
-    ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
-    ...(params.history !== undefined ? { history: params.history } : {}),
-    // API Gateway terminates TLS before the Lambda is invoked, so every
-    // WebSocket connection is secure → user mode `S`.
-    secure: true,
-  });
-
-  try {
+      connId: params.connectionId,
+      handlers,
+      managementApi: params.managementApi,
+      clock,
+      ...(params.configLoader !== undefined ? { configLoader: params.configLoader } : {}),
+    });
+    const channelAccess = new LambdaChannelAccess(runtime, clock.now());
+    const actor = new ConnectionActor({
+      state,
+      runtime,
+      channels: channelAccess,
+      serverConfig: params.serverConfig,
+      configSource: 'Secrets Manager',
+      clock,
+      ids,
+      motd: params.motd,
+      transport: { feed: (chunk) => frameToLines(chunk, wsMode) },
+      // AwsStats Scans Connections + ChannelMeta for LUSERS/STATS.
+      // `uptimeStartedAt` is captured at the Lambda's cold start so `STATS u`
+      // reports per-isolate uptime; a deployment-wide uptime would require a
+      // persistent record (future work).
+      stats: new AwsStats({
+        dynamo: params.dynamo,
+        tables: params.tables,
+        uptimeStartedAt: LAMBDA_STARTUP_AT,
+      }),
+      ...(params.messages !== undefined ? { messages: params.messages } : {}),
+      ...(params.services !== undefined ? { services: params.services } : {}),
+      ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
+      ...(params.history !== undefined ? { history: params.history } : {}),
+      // API Gateway terminates TLS before the Lambda is invoked, so every
+      // WebSocket connection is secure → user mode `S`.
+      secure: true,
+    });
     await actor.receiveTextFrame(params.body);
-  } catch (err: unknown) {
-    console.error('[irc-handler] actor.receiveTextFrame failed', err);
-    // Still persist the state — partial mutations are valuable for debug.
-    await persistState(params.dynamo, params.tables, params.connectionId, state, clock.now());
-    await params.services?.flush();
-    return { statusCode: 500 };
+  };
+
+  for (let attempt = 0; ; attempt++) {
+    // 1. Strongly-consistent read.
+    const result = await params.dynamo.send(
+      new GetCommand({
+        TableName: params.tables.Connections,
+        Key: { connectionId: params.connectionId },
+        ConsistentRead: true,
+      }),
+    );
+    if (result.Item === undefined) {
+      // Row gone (client reconnected elsewhere, swept, or stale connId).
+      // Not retriable: surface the 410 so the client reconnects.
+      console.warn(
+        `[irc-handler] $default connId=${params.connectionId} wsMode=? row=missing -> 410`,
+      );
+      return { statusCode: 410 };
+    }
+    const persisted = result.Item as unknown as MarshalledConnection;
+    const state = unmarshalConnection(persisted);
+    const expectedRevision = persisted.revision ?? 0;
+    const wsMode: WsFrameMode = persisted.wsMode ?? 'legacy';
+    wsModeHolder = wsMode;
+
+    // 2. Mark activity + run the actor. Self-sends reset per attempt.
+    state.lastSeen = clock.now();
+    outbound.length = 0;
+    try {
+      await runFrame(state, wsMode);
+    } catch (err: unknown) {
+      console.error('[irc-handler] actor.receiveTextFrame failed', err);
+      // Best-effort persist of partial state (swallow a conflict here —
+      // the actor already failed, no point retrying).
+      await persistState(params.dynamo, params.tables, state, clock.now(), expectedRevision).catch(
+        () => {},
+      );
+      await params.services?.flush();
+      return { statusCode: 500 };
+    }
+
+    // 3. Conditional persist.
+    try {
+      await persistState(params.dynamo, params.tables, state, clock.now(), expectedRevision);
+      break; // committed — exit the retry loop.
+    } catch (err: unknown) {
+      if (isConditionalCheckFailed(err) && attempt < MAX_RETRIES) {
+        // Another invocation wrote first; re-read + re-run against fresh state.
+        continue;
+      }
+      // Exhausted retries or an unrelated DynamoDB error.
+      console.error('[irc-handler] persist failed (retries exhausted or unrecoverable)', err);
+      await params.services?.flush();
+      return { statusCode: 500 };
+    }
   }
 
-  // Persist the mutated state and flush outbound bytes.
-  await persistState(params.dynamo, params.tables, params.connectionId, state, clock.now());
-  // Drain any services write-behind ops (NickServ/ChanServ/...) so a
-  // Lambda freeze / evict does not lose state.
+  // Persist committed. Drain any services write-behind ops (NickServ/ChanServ/...)
+  // so a Lambda freeze / evict does not lose state.
   await params.services?.flush();
 
   // In production, deliver outbound bytes back to the caller via APIGW.
@@ -243,7 +268,7 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
   // receive every line CRLF-joined in a single message.
   if (params.managementApi !== null && outbound.length > 0) {
     try {
-      await postOutbound(params.managementApi, params.connectionId, outbound, wsMode);
+      await postOutbound(params.managementApi, params.connectionId, outbound, wsModeHolder);
     } catch (err) {
       // Surface the failure (gone connection, stale MANAGEMENT_URL, …)
       // so it shows in CloudWatch instead of vanishing. The handler still
@@ -280,28 +305,34 @@ async function postOutbound(
 /**
  * Writes the actor's mutated `state` back to the Connections row.
  *
- * Uses an `UpdateCommand` that SETs every actor-owned field EXCEPT
- * `joinedChannels`. The membership transaction (see `AwsRuntime`)
- * owns `joinedChannels` atomically; if this frame's full-state write
- * touched it, a concurrent `$default` for the same connection would
- * lose the other frame's JOIN/PART. Optional fields (nick, user, …)
- * are SET when present and REMOVE'd when absent so a cleared value
- * does not linger from a previous frame.
+ * Uses a conditional `UpdateCommand` that SETs every actor-owned field
+ * EXCEPT `joinedChannels`, bumps the `revision` counter, and requires
+ * the row's `revision` to still equal `expectedRevision` (the value read
+ * at the start of this invocation). A `ConditionalCheckFailedException`
+ * means another concurrent `$default` for the same connection wrote in
+ * between; {@link handleDefault} catches it and retries the whole
+ * read → run → persist cycle against the fresh row. The membership
+ * transaction (see `AwsRuntime`) owns `joinedChannels` atomically and
+ * is idempotent (`ADD`/`DELETE` on a String Set), so a retried frame
+ * never doubles roster state. Optional fields (nick, user, …) are SET
+ * when present and REMOVE'd when absent so a cleared value does not
+ * linger from a previous frame.
  */
 async function persistState(
   dynamo: DynamoDBDocumentClient,
   tables: TablesConfig,
-  _connId: string,
   state: ConnectionState,
   now: number,
+  expectedRevision: number,
 ): Promise<void> {
-  const expr = buildPersistUpdate(state, now);
+  const expr = buildPersistUpdate(state, now, expectedRevision);
   const hasNames = Object.keys(expr.expressionAttributeNames).length > 0;
   await dynamo.send(
     new UpdateCommand({
       TableName: tables.Connections,
       Key: { connectionId: state.id },
       UpdateExpression: expr.updateExpression,
+      ConditionExpression: expr.conditionExpression,
       ExpressionAttributeValues: expr.expressionAttributeValues,
       ...(hasNames ? { ExpressionAttributeNames: expr.expressionAttributeNames } : {}),
     }),
@@ -326,12 +357,27 @@ const OPTIONAL_FIELDS = [
  * the required fields; SETs optional fields that are present and
  * REMOVEs those that are absent. `joinedChannels` is intentionally
  * excluded — owned by the membership transaction.
+ *
+ * **Optimistic concurrency:** the expression also `ADD`s `1` to the
+ * `revision` counter and attaches a `ConditionExpression` requiring
+ * `revision = :expectedRev` (or `attribute_not_exists(#rev)` for rows
+ * written before the field shipped). {@link handleDefault} captures the
+ * row's revision at read time and passes it as `expectedRevision`; a
+ * `ConditionalCheckFailedException` means another concurrent invocation
+ * for the same connection wrote in between → the caller re-reads and
+ * re-runs the frame (see {@link handleDefault}'s retry loop). Without
+ * this guard, two concurrent `$default` invocations (API Gateway
+ * dispatches a client's rapid frames as overlapping Lambdas) clobber
+ * each other's state — the registration deadlock where `CAP END`'s
+ * `capNegotiating=false` was overwritten by `NICK`/`USER`'s stale read.
  */
-function buildPersistUpdate(
+export function buildPersistUpdate(
   state: ConnectionState,
   now: number,
+  expectedRevision: number,
 ): {
   updateExpression: string;
+  conditionExpression: string;
   expressionAttributeNames: Record<string, string>;
   expressionAttributeValues: Record<string, unknown>;
 } {
@@ -343,6 +389,10 @@ function buildPersistUpdate(
     ':ls': state.lastSeen,
     ':is': now,
     ':v': CONNECTION_VERSION,
+    // Optimistic-concurrency: increment the revision counter, gated by
+    // a condition that the row is still at the revision we read.
+    ':revInc': 1,
+    ':expectedRev': expectedRevision,
   };
   const setNames = [
     'registration = :reg',
@@ -354,7 +404,7 @@ function buildPersistUpdate(
     'version = :v',
   ];
   const removeNames: string[] = [];
-  const nameMap: Record<string, string> = {};
+  const nameMap: Record<string, string> = { '#rev': 'revision' };
 
   for (const field of OPTIONAL_FIELDS) {
     const placeholder = `:${field}`;
@@ -373,13 +423,30 @@ function buildPersistUpdate(
   if (removeNames.length > 0) {
     parts.push(`REMOVE ${removeNames.join(', ')}`);
   }
+  // Bump the optimistic-concurrency counter atomically with the state write.
+  parts.push('ADD #rev :revInc');
   return {
     updateExpression: parts.join(' '),
+    // `attribute_not_exists(#rev)` lets the first write after deploy land on
+    // pre-existing rows that predate the column (treats them as revision 0).
+    conditionExpression: 'attribute_not_exists(#rev) OR #rev = :expectedRev',
     expressionAttributeNames: nameMap,
     expressionAttributeValues: values,
   };
 }
 
+/**
+ * Returns true when a DynamoDB error is a conditional-check failure
+ * (the row's `revision` no longer matches the value the invocation
+ * read). Such failures are retried by {@link handleDefault}'s
+ * optimistic-concurrency loop after re-reading and re-running the frame.
+ */
+export function isConditionalCheckFailed(err: unknown): boolean {
+  if (err === null || typeof err !== 'object') return false;
+  const name = (err as { name?: string }).name;
+  return name === 'ConditionalCheckFailedException';
+}
+
 /**
  * `ActorChannelAccess` backed by the per-invocation {@link AwsRuntime}.
  *