serverless-ircd 0.10.0 → 0.11.0

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

@@ -11,7 +11,7 @@
  */
 
 import type { BatchWriteCommandInput } from '@aws-sdk/lib-dynamodb';
-import { FakeClock } from '@serverless-ircd/irc-core';
+import { FakeClock, certIdentityFromSubject } from '@serverless-ircd/irc-core';
 import { describe, expect, it } from 'vitest';
 import { DynamoServicesStore, loadDynamoServicesStore } from '../src/dynamo-services-store';
 
@@ -174,6 +174,32 @@ describe('DynamoServicesStore — round-trip via fake DDB', () => {
     expect(reloaded.verifyNick('alice', 'hunter2').ok).toBe(false);
   });
 
+  it('persists the identify-failure throttle and round-trips the freeze', async () => {
+    const clock = new FakeClock(NOW);
+    const { client } = makeFakeClient();
+    const first = await loadDynamoServicesStore(asClient(client), 'Services', clock);
+    if (first === undefined) throw new Error('store not loaded');
+    first.registerNick('alice', 'hunter2', 'a@x');
+    clock.advance(10);
+    first.recordIdentifyFailure('alice');
+    clock.advance(10);
+    first.recordIdentifyFailure('alice');
+    await first.flush();
+
+    // Fresh connection / deploy: the reload still sees the freeze.
+    const reloaded = await reload(client);
+    expect(reloaded.isNickIdentifyFrozen('alice', { maxFailures: 2, windowMs: 300_000 })).toBe(
+      true,
+    );
+    expect(reloaded.clearIdentifyFailures('alice')).toBe(2);
+
+    // The cleared state round-trips too.
+    await reloaded.flush();
+    const after = await reload(client);
+    expect(after.isNickIdentifyFrozen('alice', { maxFailures: 1, windowMs: 300_000 })).toBe(false);
+    expect(after.clearIdentifyFailures('alice')).toBe(0);
+  });
+
   it('drops a NickServ registration after flush + reload', async () => {
     const { store, client } = await fresh();
     store.registerNick('alice', 'pw', 'a@x');
@@ -184,6 +210,54 @@ describe('DynamoServicesStore — round-trip via fake DDB', () => {
     expect((await reload(client)).isRegisteredNick('alice')).toBe(false);
   });
 
+  it('round-trips a bound cert fingerprint and verifies EXTERNAL after reload', async () => {
+    // A cert binding attached before a deploy must still authenticate a
+    // SASL EXTERNAL client after the store rehydrates from DynamoDB —
+    // the production path for certificate-backed login.
+    const { store, client } = await fresh();
+    store.registerNick('alice', 'hunter2', 'a@x');
+    store.addCertFingerprint('alice', 'AA112233445566778899AABBCCDDEEFF');
+    await store.flush();
+
+    const reloaded = await reload(client);
+    // The fingerprint is normalised (lowercase, colon-free) on the round-trip.
+    expect(reloaded.getNick('alice')?.certSubjects).toEqual([
+      'fp:aa112233445566778899aabbccddeeff',
+    ]);
+    expect(
+      reloaded.verifyCertFP(
+        certIdentityFromSubject('CN=alice', 'aa112233445566778899aabbccddeeff'),
+      ),
+    ).toEqual({ ok: true, account: 'alice' });
+  });
+
+  it('round-trips a bound subject DN and verifies EXTERNAL via the canonical DN arm', async () => {
+    const { store, client } = await fresh();
+    store.registerNick('alice', 'hunter2', 'a@x');
+    store.addCertFP('alice', 'CN=alice,O=Example Inc');
+    await store.flush();
+
+    const reloaded = await reload(client);
+    // Platform-surfaced DN in a different RDN order still matches (canonical compare).
+    expect(reloaded.verifyCertFP(certIdentityFromSubject('O=Example Inc,CN=alice'))).toEqual({
+      ok: true,
+      account: 'alice',
+    });
+  });
+
+  it('keeps EXTERNAL verify failing for an unbound cert after reload', async () => {
+    const { store, client } = await fresh();
+    store.registerNick('alice', 'hunter2', 'a@x');
+    store.addCertFingerprint('alice', 'aa112233445566778899aabbccddeeff');
+    await store.flush();
+
+    const reloaded = await reload(client);
+    expect(
+      reloaded.verifyCertFP(certIdentityFromSubject('CN=alice', 'ffffffffffffffffffffffffffffffff'))
+        .ok,
+    ).toBe(false);
+  });
+
   it('persists channel + access + levels + topic, then drops the whole subtree', async () => {
     const { store, client } = await fresh();
     store.registerChannel('#chan', 'alice');
@@ -324,6 +398,54 @@ describe('DynamoServicesStore — round-trip via fake DDB', () => {
 });
 
 describe('DynamoServicesStore — snapshot coercion tolerance', () => {
+  it('defaults the identify-throttle fields on a legacy nick item (attrs absent)', async () => {
+    // A nick item written before the identify throttle existed carries no
+    // identifyFailures / pendingIdentifyFailureNotice attributes.
+    const { client, items } = makeFakeClient();
+    items.set('NICK:alice\x00#', {
+      pk: 'NICK:alice',
+      sk: '#',
+      type: 'nick',
+      nick: 'alice',
+      account: 'alice',
+      email: 'a@x',
+      createdAt: NOW,
+      enforce: 'none',
+      // Mixed-types array: exercises the string-filter callback on load.
+      certSubjects: ['CN=alice', 7],
+      algorithm: 'scrypt',
+      salt: 'c2FsdA==',
+      hash: 'aGFzaA==',
+    });
+    const store = await loadDynamoServicesStore(asClient(client), 'Services', new FakeClock(NOW));
+    if (store === undefined) throw new Error('store not loaded');
+    expect(store.isRegisteredNick('alice')).toBe(true);
+    expect(store.getNick('alice')?.certSubjects).toEqual(['CN=alice']);
+    expect(store.isNickIdentifyFrozen('alice', { maxFailures: 1, windowMs: 300_000 })).toBe(false);
+    expect(store.clearIdentifyFailures('alice')).toBe(0);
+    // Ill-typed throttle attributes collapse to the same neutral defaults.
+    items.set('NICK:bob\x00#', {
+      pk: 'NICK:bob',
+      sk: '#',
+      type: 'nick',
+      nick: 'bob',
+      account: 'bob',
+      email: 'b@x',
+      createdAt: NOW,
+      enforce: 'none',
+      certSubjects: [],
+      identifyFailures: 'soon',
+      pendingIdentifyFailureNotice: 'many',
+      algorithm: 'scrypt',
+      salt: 'c2FsdA==',
+      hash: 'aGFzaA==',
+    });
+    const second = await loadDynamoServicesStore(asClient(client), 'Services', new FakeClock(NOW));
+    if (second === undefined) throw new Error('store not loaded');
+    expect(second.isNickIdentifyFrozen('bob', { maxFailures: 1, windowMs: 300_000 })).toBe(false);
+    expect(second.clearIdentifyFailures('bob')).toBe(0);
+  });
+
   it('skips items with unknown or ill-typed fields', async () => {
     // Hand-craft malformed items directly in the fake table.
     const { client, items } = makeFakeClient();

package/packages/aws-adapter/tests/handlers.test.ts

@@ -62,7 +62,7 @@ async function makeFixture(): Promise<Fixture> {
     const pkName = props.partitionKey?.name;
     const skName = props.sortKey?.name;
     if (pkName === undefined) throw new Error(`table ${logical} missing partitionKey`);
-    const attributeDefinitions: Array<{ AttributeName: string; AttributeType: 'S' }> = [
+    const attributeDefinitions: Array<{ AttributeName: string; AttributeType: 'S' | 'N' }> = [
       { AttributeName: pkName, AttributeType: 'S' },
     ];
     const keySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
@@ -72,11 +72,33 @@ async function makeFixture(): Promise<Fixture> {
       attributeDefinitions.push({ AttributeName: skName, AttributeType: 'S' });
       keySchema.push({ AttributeName: skName, KeyType: 'RANGE' });
     }
+    // Mirror the CDK-declared secondary indexes (the Connections per-IP
+    // admission GSI) so the fixture matches the deployed schema.
+    const globalSecondaryIndexes = (props.globalSecondaryIndexes ?? []).map((g) => {
+      const gpk = g.partitionKey;
+      if (gpk === undefined) throw new Error(`index ${g.indexName} missing partitionKey`);
+      const gsiKeySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
+        { AttributeName: gpk.name, KeyType: 'HASH' },
+      ];
+      attributeDefinitions.push({ AttributeName: gpk.name, AttributeType: 'S' });
+      if (g.sortKey !== undefined) {
+        gsiKeySchema.push({ AttributeName: g.sortKey.name, KeyType: 'RANGE' });
+        attributeDefinitions.push({ AttributeName: g.sortKey.name, AttributeType: 'N' });
+      }
+      return {
+        IndexName: g.indexName,
+        KeySchema: gsiKeySchema,
+        Projection: { ProjectionType: 'ALL' as const },
+      };
+    });
     await client.send(
       new CreateTableCommand({
         TableName: `${prefix}${logical}`,
         AttributeDefinitions: attributeDefinitions,
         KeySchema: keySchema,
+        ...(globalSecondaryIndexes.length > 0
+          ? { GlobalSecondaryIndexes: globalSecondaryIndexes }
+          : {}),
         BillingMode: 'PAY_PER_REQUEST',
       }),
     );
@@ -257,6 +279,40 @@ describe.skipIf(!available)('handlers', () => {
       });
       expect((await probe.getConnectionInfo('b1'))?.id).toBe('b1');
     });
+
+    it('rejects the per-IP cap via identity.sourceIp and the sourceIp GSI', async () => {
+      // End-to-end per-IP admission: dispatch feeds
+      // `event.requestContext.identity.sourceIp` into handleConnect,
+      // which counts the IP's live rows on the `sourceIp` GSI and fires
+      // the (previously dead) maxConnectionsPerIp branch.
+      const capped: HandlerDeps = {
+        ...requireFx().deps,
+        serverConfig: { ...SERVER_CONFIG, maxClients: 50, maxConnectionsPerIp: 2 },
+      };
+      const fromIp = (id: string, ip: string) =>
+        dispatch(
+          {
+            requestContext: { routeKey: '$connect', connectionId: id, identity: { sourceIp: ip } },
+          },
+          capped,
+        );
+      expect((await fromIp('ip-a1', '203.0.113.30')).statusCode).toBe(200);
+      expect((await fromIp('ip-a2', '203.0.113.30')).statusCode).toBe(200);
+      const third = await fromIp('ip-a3', '203.0.113.30');
+      expect(third.statusCode).toBe(429);
+      expect(third.body).toBe('too many connections from this IP');
+      // A different IP is unaffected — the budget is keyed per IP.
+      expect((await fromIp('ip-b1', '198.51.100.30')).statusCode).toBe(200);
+      // The rejected connection must NOT be recorded.
+      const probe = new AwsRuntime({
+        dynamo: requireFx().client,
+        tables: requireFx().tables,
+        connId: '__probe__',
+        handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+        managementApi: null,
+      });
+      expect(await probe.getConnectionInfo('ip-a3')).toBeNull();
+    });
   });
 
   // -------------------------------------------------------------------------

package/packages/aws-adapter/tests/nlb-secure.test.ts

@@ -0,0 +1,362 @@
+/**
+ * Unit tests for the NLB TLS secure-flag propagation (user mode `S`).
+ *
+ * The stack wires the NLB streaming Lambda exclusively behind a
+ * `Protocol.TLS` listener (ACM-cert terminated at the edge), so every
+ * connection on that entry is TLS-protected. These tests pin the
+ * propagation of that fact end-to-end:
+ *   - the `nlbStreamHandler` dispatcher (`dispatchNlbStream`) asserts
+ *     `secure: true`, so registration stamps read-only user mode `S`
+ *     (visible via `MODE` → `221 … +S`) and the Connections row
+ *     persists both `secure` and `userModes.tls`;
+ *   - STS reflects the secure transport (`CAP LS` advertises the
+ *     duration-only TLS form, never the plaintext `port=` upgrade form);
+ *   - SASL EXTERNAL negotiation is permitted on the secure path (the
+ *     mech is accepted when an mTLS provider is bound; the verify-level
+ *     `904` for a missing account is owned by the EXTERNAL-verify
+ *     ticket, not a secure-connection refusal);
+ *   - a plain transport (secure not asserted) stays unflagged.
+ *
+ * Uses real DynamoDB Local, mirroring `nlb-stream.test.ts`.
+ */
+
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import { GetCommand } from '@aws-sdk/lib-dynamodb';
+import {
+  InMemoryMtlsIdentityProvider,
+  type ParsedServerConfig,
+  StaticMotdProvider,
+  certIdentityFromSubject,
+} from '@serverless-ircd/irc-core';
+import { makeTestServerConfig } from '@serverless-ircd/irc-test-support';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { PostToConnection } from '../src/aws-runtime.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+import { type HandlerDeps, dispatchNlbStream } from '../src/handlers/index.js';
+import {
+  type NlbStreamEvent,
+  deriveNlbConnectionId,
+  handleNlbStream,
+} from '../src/handlers/nlb-stream.js';
+import { bindMessageStore } from '../src/message-store.js';
+import type { TablesConfig } from '../src/tables.js';
+
+const available = process.env.DDB_AVAILABLE === '1';
+const endpoint = process.env.DYNAMO_ENDPOINT;
+
+const SERVER_CONFIG: ParsedServerConfig = makeTestServerConfig({
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  motdLines: ['Welcome to the test IRC server.'],
+  // SASL EXTERNAL is operator opt-in; these tests exercise the enabled
+  // deployment (mTLS + TLS listener configured at the edge).
+  sasl: { externalEnabled: true },
+});
+
+const STS_CONFIG: ParsedServerConfig = makeTestServerConfig({
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  motdLines: ['Welcome to the test IRC server.'],
+  sts: { duration: 3600, port: 6697 },
+});
+
+const MOTD = new StaticMotdProvider(SERVER_CONFIG.motdLines);
+
+interface Fixture {
+  tables: TablesConfig;
+  client: ReturnType<typeof createDynamoDocumentClient>;
+  mgmt: LocalPostToConnection;
+  deps: HandlerDeps;
+  stsDeps: HandlerDeps;
+  cleanup: () => Promise<void>;
+}
+
+let fx: Fixture | null;
+
+function requireFx(): Fixture {
+  if (!fx) throw new Error('test fixture not initialized');
+  return fx;
+}
+
+async function makeFixture(): Promise<Fixture> {
+  if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
+  const prefix = `s${Date.now()}-${Math.floor(Math.random() * 1e6)}-`;
+  const tables = Object.fromEntries(
+    Object.keys(TABLE_DEFS).map((name) => [name, `${prefix}${name}`]),
+  ) as TablesConfig;
+  const client = createDynamoDocumentClient({ endpoint });
+  for (const [logical, props] of Object.entries(TABLE_DEFS)) {
+    const pkName = props.partitionKey?.name;
+    const skName = props.sortKey?.name;
+    if (pkName === undefined) throw new Error(`table ${logical} missing partitionKey`);
+    const attributeDefinitions: Array<{ AttributeName: string; AttributeType: 'S' | 'N' }> = [
+      { AttributeName: pkName, AttributeType: 'S' },
+    ];
+    const keySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
+      { AttributeName: pkName, KeyType: 'HASH' },
+    ];
+    if (skName !== undefined) {
+      attributeDefinitions.push({ AttributeName: skName, AttributeType: 'S' });
+      keySchema.push({ AttributeName: skName, KeyType: 'RANGE' });
+    }
+    // Secondary indexes declared by the CDK definition (the Connections
+    // per-IP admission GSI) are created here too — the NLB new-flow rate
+    // gate Queries the index, so a fixture without it diverges from the
+    // deployed schema.
+    const globalSecondaryIndexes = (props.globalSecondaryIndexes ?? []).map((g) => {
+      const gpk = g.partitionKey;
+      if (gpk === undefined) throw new Error(`index ${g.indexName} missing partitionKey`);
+      const gsiKeySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
+        { AttributeName: gpk.name, KeyType: 'HASH' },
+      ];
+      attributeDefinitions.push({ AttributeName: gpk.name, AttributeType: 'S' });
+      if (g.sortKey !== undefined) {
+        gsiKeySchema.push({ AttributeName: g.sortKey.name, KeyType: 'RANGE' });
+        attributeDefinitions.push({ AttributeName: g.sortKey.name, AttributeType: 'N' });
+      }
+      return {
+        IndexName: g.indexName,
+        KeySchema: gsiKeySchema,
+        Projection: { ProjectionType: 'ALL' as const },
+      };
+    });
+    await client.send(
+      new CreateTableCommand({
+        TableName: `${prefix}${logical}`,
+        AttributeDefinitions: attributeDefinitions,
+        KeySchema: keySchema,
+        ...(globalSecondaryIndexes.length > 0
+          ? { GlobalSecondaryIndexes: globalSecondaryIndexes }
+          : {}),
+        BillingMode: 'PAY_PER_REQUEST',
+      }),
+    );
+  }
+  const mgmt = new LocalPostToConnection();
+  const deps: HandlerDeps = {
+    dynamo: client,
+    tables,
+    serverConfig: SERVER_CONFIG,
+    motd: MOTD,
+    messages: bindMessageStore(SERVER_CONFIG),
+    managementApi: mgmt as never,
+  };
+  const stsDeps: HandlerDeps = {
+    ...deps,
+    serverConfig: STS_CONFIG,
+    messages: bindMessageStore(STS_CONFIG),
+  };
+  return {
+    tables,
+    client,
+    mgmt,
+    deps,
+    stsDeps,
+    cleanup: async () => {
+      for (const logical of Object.keys(TABLE_DEFS)) {
+        try {
+          await client.send(new DeleteTableCommand({ TableName: `${prefix}${logical}` }));
+        } catch {
+          // Already gone.
+        }
+      }
+    },
+  };
+}
+
+/** Builds an NLB event from raw client bytes (base64-encodes the body). */
+function nlbEvent(sourceIp: string, sourcePort: string, data: string): NlbStreamEvent {
+  return {
+    requestContext: { elb: { targetGroupArn: 'arn:aws:elasticloadbalancing:::targetgroup/test' } },
+    version: '2.0',
+    body: Buffer.from(data, 'utf8').toString('base64'),
+    isBase64Encoded: true,
+    headers: {
+      'x-forwarded-for': sourceIp,
+      'x-forwarded-port': sourcePort,
+    },
+  };
+}
+
+/** Decodes an NLB response body back to raw IRC bytes. */
+function decodeBody(res: { body: string }): string {
+  return Buffer.from(res.body, 'base64').toString('utf8');
+}
+
+/** Reads a raw Connections row. */
+async function readRow(
+  tableName: string,
+  client: Fixture['client'],
+  connId: string,
+): Promise<Record<string, unknown> | undefined> {
+  const row = await client.send(
+    new GetCommand({ TableName: tableName, Key: { connectionId: connId } }),
+  );
+  return row.Item;
+}
+
+describe.skipIf(!available)('NLB TLS secure-flag propagation', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('flags the NLB+TLS connection secure: MODE read-back shows +S and the row persists secure + userModes.tls', async () => {
+    const f = requireFx();
+    const res = await dispatchNlbStream(
+      nlbEvent(
+        '10.0.0.70',
+        '50070',
+        'NICK tlsclient\r\nUSER tls 0 * :TLS User\r\nMODE tlsclient\r\n',
+      ),
+      f.deps,
+    );
+    expect(res.statusCode).toBe(200);
+    const body = decodeBody(res);
+    // Read-only user mode `S` is visible in the MODE read form (221).
+    expect(body).toContain('221 tlsclient +S');
+    expect(body).not.toContain('221 tlsclient +\r\n');
+
+    // The persisted row carries the TLS fact for cross-invocation readers.
+    const row = await readRow(
+      f.tables.Connections,
+      f.client,
+      deriveNlbConnectionId('10.0.0.70', '50070'),
+    );
+    expect(row?.secure).toBe(true);
+    expect(row?.userModes).toMatchObject({ tls: true });
+  });
+
+  it('keeps the secure flag across invocations of the same flow (persist + re-stamp)', async () => {
+    const f = requireFx();
+    await dispatchNlbStream(
+      nlbEvent('10.0.0.71', '50071', 'NICK reuser\r\nUSER u 0 * :Re User\r\n'),
+      f.deps,
+    );
+    const res = await dispatchNlbStream(nlbEvent('10.0.0.71', '50071', 'MODE reuser\r\n'), f.deps);
+    expect(res.statusCode).toBe(200);
+    expect(decodeBody(res)).toContain('221 reuser +S');
+
+    const row = await readRow(
+      f.tables.Connections,
+      f.client,
+      deriveNlbConnectionId('10.0.0.71', '50071'),
+    );
+    expect(row?.secure).toBe(true);
+    expect(row?.userModes).toMatchObject({ tls: true });
+  });
+
+  it('does not flag a plain transport when secure is not asserted (contrast)', async () => {
+    const f = requireFx();
+    // handleNlbStream called WITHOUT `secure` models a plain-TCP listener
+    // target: no S mode, and the row records the plain transport.
+    const res = await handleNlbStream(
+      nlbEvent(
+        '10.0.0.72',
+        '50072',
+        'NICK plainclient\r\nUSER p 0 * :Plain User\r\nMODE plainclient\r\n',
+      ),
+      {
+        dynamo: f.client,
+        tables: f.tables,
+        serverConfig: SERVER_CONFIG,
+        motd: MOTD,
+        messages: bindMessageStore(SERVER_CONFIG),
+        managementApi: f.mgmt,
+      },
+    );
+    expect(res.statusCode).toBe(200);
+    const body = decodeBody(res);
+    expect(body).toContain('221 plainclient +\r\n');
+    expect(body).not.toContain('+S');
+
+    const row = await readRow(
+      f.tables.Connections,
+      f.client,
+      deriveNlbConnectionId('10.0.0.72', '50072'),
+    );
+    expect(row?.secure).toBe(false);
+    expect(row?.userModes).toMatchObject({ tls: false });
+  });
+
+  it('advertises the TLS form of sts on the secure NLB path (duration only, no port)', async () => {
+    const f = requireFx();
+    const res = await dispatchNlbStream(
+      nlbEvent('10.0.0.73', '50073', 'CAP LS 302\r\n'),
+      f.stsDeps,
+    );
+    expect(res.statusCode).toBe(200);
+    const body = decodeBody(res);
+    // Already on the secure listener: duration-only advertisement.
+    expect(body).toContain('sts=duration=3600');
+    expect(body).not.toContain('port=');
+
+    // Contrast — the same config over a transport that did not assert
+    // secure advertises the plaintext upgrade form with the port.
+    const plain = await handleNlbStream(nlbEvent('10.0.0.74', '50074', 'CAP LS 302\r\n'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: STS_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(STS_CONFIG),
+      managementApi: f.mgmt,
+    });
+    expect(decodeBody(plain)).toContain('sts=duration=3600,port=6697');
+  });
+
+  it('permits SASL EXTERNAL negotiation on the secure NLB path', async () => {
+    const f = requireFx();
+    const connId = deriveNlbConnectionId('10.0.0.75', '50075');
+    const opts = {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+      secure: true,
+      mtlsIdentity: new InMemoryMtlsIdentityProvider([
+        { connId, identity: certIdentityFromSubject('CN=extuser') },
+      ]),
+    };
+
+    // Mechanism selection: EXTERNAL is advertised and accepted (the
+    // server asks for the empty payload with `AUTHENTICATE +`).
+    const ls = await handleNlbStream(
+      nlbEvent('10.0.0.75', '50075', 'CAP LS 302\r\nAUTHENTICATE EXTERNAL\r\n'),
+      opts,
+    );
+    const lsBody = decodeBody(ls);
+    expect(lsBody).toContain('sasl=PLAIN,EXTERNAL');
+    expect(lsBody).toContain('AUTHENTICATE +');
+
+    // Payload delivery: the exchange proceeds to the verify step. With no
+    // services store bound the verify fails with 904 (account resolution
+    // is the EXTERNAL-verify ticket's concern) — never a 908 mech-level
+    // refusal on secure-connection grounds.
+    const fin = await handleNlbStream(nlbEvent('10.0.0.75', '50075', 'AUTHENTICATE +\r\n'), opts);
+    const finBody = decodeBody(fin);
+    expect(finBody).toContain('904');
+    expect(finBody).not.toContain('908');
+  });
+});
+
+/**
+ * Test double for `ApiGatewayManagementApi`. Routes `postToConnection`
+ * calls to a registered sink for `ConnectionId`.
+ */
+class LocalPostToConnection implements PostToConnection {
+  private readonly sinks = new Map<string, (data: string) => void>();
+  register(connId: string, sink: (data: string) => void): void {
+    this.sinks.set(connId, sink);
+  }
+  async postToConnection(input: { ConnectionId: string; Data: string }): Promise<unknown> {
+    const sink = this.sinks.get(input.ConnectionId);
+    if (sink !== undefined) sink(input.Data);
+    return {};
+  }
+}