serverless-ircd 0.10.0 → 0.11.0

package/apps/local-cli/tests/tcp.test.ts

@@ -275,6 +275,35 @@ describe('local-cli TCP transport — IRC flows', () => {
     await client.close();
   });
 
+  it('closes the TCP connection with ERROR when the input buffer cap is exceeded', async () => {
+    // A peer streaming > 8 KiB with no line terminator would grow the
+    // LineScanner carry unboundedly; the server must answer with the
+    // RFC-style ERROR notice, destroy the socket, and unregister the
+    // connection from the runtime.
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK overflower');
+    await client.send('USER overflower 0 * :Over');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    const connId = await server.runtime.lookupNick('overflower');
+    expect(connId).not.toBeNull();
+    expect(server.runtime.hasConnection(connId as string)).toBe(true);
+
+    const closed = new Promise<void>((resolve) => client.socket.once('close', () => resolve()));
+    await client.writeRaw('x'.repeat(9 * 1024)); // no terminator anywhere
+    const errorLine = await client.waitFor(
+      (l) => l === 'ERROR :Closing link: input buffer overflow',
+      2_000,
+    );
+    expect(errorLine).toBe('ERROR :Closing link: input buffer overflow');
+    await closed;
+    expect(client.socket.destroyed).toBe(true);
+    // Cleanup ran: the runtime no longer tracks the connection.
+    await new Promise((r) => setTimeout(r, 100));
+    expect(server.runtime.hasConnection(connId as string)).toBe(false);
+  });
+
   it('logs an actor failure on the TCP path without crashing the server', async () => {
     const original = server.runtime.send.bind(server.runtime);
     server.runtime.send = async () => {

package/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/web",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "description": "Web client workspace: Kiwi IRC SPA served at /webclient/ and project landing page at /",
   "license": "BSD-3-Clause",

package/docs/AWS-Deployment.md

@@ -381,10 +381,12 @@ For a real production deployment, before your first `pnpm deploy:aws`:
 1. **Use a dedicated AWS account** (or at least a dedicated region) for
    production. Do not point production credentials at the same stack
    CI is deploying to on every push.
-2. **Change `RemovalPolicy.DESTROY` to `RemovalPolicy.RETAIN`** on the
-   five DynamoDB tables (see §9.4). The committed stack deletes all
-   data on `cdk destroy` — intentional for staging, dangerous for
-   production.
+2. **Keep the default table protection on.** State-bearing tables
+   (`Nicks`, `Services`, `ChannelMeta`, `ChannelMembers`) default to
+   `RemovalPolicy.RETAIN` + `deletionProtection: true` + PITR-on, so a
+   mistaken `cdk destroy` or a stray `aws dynamodb delete-table` cannot
+   wipe them (see §9.4). Only set `-c allowTableDeletion=true` for a
+   deliberate teardown.
 3. **Set the server identity** (`SERVER_NAME`, `NETWORK_NAME`,
    `MOTD`) — see §7.1. `SERVER_NAME` is required at boot; the stack
    falls back to `irc.localhost` when the prop is omitted, which is
@@ -498,6 +500,13 @@ any of them** — to enable one, add an `addEnvironment(...)` line in
 | `MAX_LIST_ENTRIES`        | int     | `maxListEntries`      |
 | `QUIT_MESSAGE`            | string  | `quitMessage`         |
 | `SASL_ACCOUNTS`           | string  | `saslAccounts`        |
+| `MAX_CONNECTIONS_PER_IP`  | int     | `maxConnectionsPerIp` |
+| `PER_IP_CONNECTION_RATE_MAX` | int  | `perIpConnectionRate.max` |
+| `PER_IP_CONNECTION_RATE_WINDOW_MS` | int | `perIpConnectionRate.windowMs` |
+
+The last three are the per-IP admission knobs (§7.8): setting only one
+half of the rate pair falls back to the schema default (5 per 60 000 ms)
+for the other half.
 
 `SASL_ACCOUNTS` is the legacy/config fallback (newline-delimited
 `username:password` pairs); it is used only when the `Accounts` table is
@@ -587,6 +596,51 @@ intentional — it cannot be set by accident. Tear the sandbox stack down
 immediately after debugging; never deploy this combination to a shared
 account.
 
+### 7.7 DynamoDB table-protection context flags
+
+Two CDK context flags control the state-bearing tables' data-loss
+protection (`Nicks`, `Services`, `ChannelMeta`, `ChannelMembers`).
+`Connections` is always `DESTROY` with no PITR and is unaffected by
+either flag. See §9.4 for the full table and the rationale (and the
+"no snapshot-on-delete" note).
+
+| Context flag           | Default | Effect when flipped                                                                 |
+|------------------------|---------|-------------------------------------------------------------------------------------|
+| `allowTableDeletion`   | `false` | `true` → state tables become `RemovalPolicy.DESTROY` + `deletionProtection: false`, so a deliberate `cdk destroy` teardown can delete them. Data is irreversibly lost. |
+| `enablePitr`           | `true`  | `false` → point-in-time recovery is disabled on every state table. Independent of `allowTableDeletion` (a teardown keeps PITR on). PITR costs ~$0.20/GB-month per table (§11.1). |
+
+Both arrive as strings on the CLI and are normalised with the shared
+`parseContextBool` helper (same path as `allowDataTrace`), so
+`-c allowTableDeletion=false` stays false-y. They map onto the
+`IrcStackProps.allowTableDeletion` / `IrcStackProps.enablePitr` construct
+props (`apps/aws-stack/bin/aws.ts`).
+
+### 7.8 Connect throttling (per-IP admission, stage limits, WAF)
+
+Connection setup is where credential brute-force spends its budget
+(`PASS` / `AUTHENTICATE` per connection), so the stack throttles it in
+three layers, outermost first:
+
+| Layer | Where | Knob | Default |
+|-------|-------|------|---------|
+| **1. WAF edge rate limit** | WAFv2 rate-based rule, associated with the stage. WAF only inspects the initial HTTP upgrade on a WebSocket API, so the rule is effectively scoped to `$connect` and never re-fires on established frames. | `-c wafConnectRateLimit=<req/5min/IP>` (CDK context; blocks at the edge before a Lambda invocation is billed) | off (no WAF resources) |
+| **2. APIGW stage throttling** | `defaultRouteSettings` on the stage — global backstop across ALL routes and IPs. | `--parameters ApiThrottlingRateLimit=…` / `--parameters ApiThrottlingBurstLimit=…` (CloudFormation parameters) | 100 rps / burst 200 |
+| **3. Per-IP admission gates** | Inside the `$connect` Lambda: a paginated Query against the `Connections` table's `sourceIp-connectedSince` GSI counts the caller IP's live connections (`maxConnectionsPerIp`) and in-window establishments (`perIpConnectionRate`); over-budget connects return `429` and no row is written. The same rate budget gates NLB new flows (§AWS-TCP-Deployment). | `MAX_CONNECTIONS_PER_IP`, `PER_IP_CONNECTION_RATE_MAX`, `PER_IP_CONNECTION_RATE_WINDOW_MS` env vars (§7.3) | 10 / 5 per 60 s |
+
+Notes:
+
+- Layer 1 is opt-in because WAFv2 web ACLs cost ~$5/mo + $1/rule + $0.60/M
+  requests; for a small deployment, layers 2+3 are usually enough. Enable
+  with `pnpm --filter @serverless-ircd/aws-stack run cdk:synth -- -c wafConnectRateLimit=2000`
+  (2000 upgrade requests per 5-minute window per client IP before the IP
+  is blocked at the edge).
+- Layer 3's per-IP counts are eventually consistent (GSI reads), so a
+  coordinated burst from one IP can slightly overshoot the cap — the same
+  best-effort TOCTOU contract as the global `maxClients` counter.
+- The 429 response carries `ERROR :Closing link` semantics at the HTTP
+  layer where possible; clients should treat it as back-pressure (retry
+  after the window decays), not a permanent ban.
+
 ---
 
 ## 8. Secrets
@@ -855,28 +909,62 @@ postToConnection, per-channel send-list cache, a dedicated fanout
 Lambda) are deferred to post-v1; the load-test ticket will surface
 the ceiling.
 
-### 9.4 Removal policy (IMPORTANT)
+### 9.4 Removal policy, deletion protection, and PITR (IMPORTANT)
+
+Every table is protected from accidental data loss by default. The
+state-bearing tables (`Nicks`, `Services`, `ChannelMeta`, `ChannelMembers`)
+get **three independent safeguards**, each toggleable so a deliberate
+teardown can still proceed; the one ephemeral table (`Connections`) is
+always DESTROY:
+
+| Table                                         | RemovalPolicy | `deletionProtection` | PITR |
+|-----------------------------------------------|---------------|----------------------|------|
+| `Nicks`, `Services`, `ChannelMeta`, `ChannelMembers` | `RETAIN` (default) | `true` (default) | `true` (default) |
+| `Connections`                                 | `DESTROY`     | (unset → off)        | (unset → off) |
+
+- **`RemovalPolicy.RETAIN`** — when the stack is deleted, CloudFormation
+  *orphans* the table instead of deleting it; the data survives.
+- **`deletionProtection: true`** — DynamoDB refuses a `DeleteTable` API
+  call while this is on, blocking a stray `aws dynamodb delete-table` even
+  from an admin or compromised credential.
+- **`pointInTimeRecovery` (PITR)** — continuous, per-table restore (within
+  the last ~35 days) against accidental writes/deletes that RETAIN +
+  deletion protection cannot stop (e.g. a buggy `UpdateItem` that
+  overwrites rows).
+
+> **No snapshot-on-delete.** DynamoDB tables do NOT snapshot when a stack
+> is deleted (`RemovalPolicy.SNAPSHOT` is a no-op here). `RETAIN` (orphan +
+> keep) + PITR (continuous, in-place restore) is the correct combination;
+> do not rely on a snapshot that does not exist.
+
+Two CDK context flags control these (threaded through `bin/aws.ts`, see
+§7.7):
+
+- **`allowTableDeletion`** (default `false`). Set `-c allowTableDeletion=true`
+  for a deliberate `cdk destroy` teardown: every state table flips to
+  `RemovalPolicy.DESTROY` with `deletionProtection: false` so CloudFormation
+  can delete them. The data is **irreversibly lost** — flip this off only
+  when you genuinely want the tables gone. `Connections` is always DESTROY
+  regardless.
+- **`enablePitr`** (default `true`). Set `-c enablePitr=false` to disable
+  PITR on every state table. Independent of `allowTableDeletion` — a
+  teardown keeps PITR on (harmless, and the data is still recoverable up
+  until the table is actually deleted). `Connections` never carries PITR.
 
-The stack sets `RemovalPolicy.DESTROY` on every table:
+```bash
+# Default deploy: state tables RETAIN + deletion-protected + PITR-on.
+pnpm --filter @serverless-ircd/aws-stack run cdk:synth
 
-```ts
-// apps/aws-stack/src/aws-stack.ts:48
-const tables = Object.entries(TABLE_DEFS).map(
-  ([logicalId, tableProps]) =>
-    new Table(this, logicalId, { ...tableProps, removalPolicy: RemovalPolicy.DESTROY }),
-);
-```
+# Deliberate teardown (state tables become DELETABLE):
+pnpm --filter @serverless-ircd/aws-stack run cdk:synth -- -c allowTableDeletion=true
 
-**This means `cdk destroy` deletes every table and all of its data.**
-This is intentional for staging (you want a clean teardown between
-experiments) and **dangerous for production**.
+# Disable PITR (e.g. cost-sensitive dev deploy):
+pnpm --filter @serverless-ircd/aws-stack run cdk:synth -- -c enablePitr=false
+```
 
-For production, fork the stack to use `RemovalPolicy.RETAIN` (or
-`RETAIN_ON_UPDATE`): tables become orphans on stack deletion and keep
-their data. There is no built-in knob for this today — it requires
-editing `aws-stack.ts`. Recommendation: ship a `production: boolean`
-stack prop in a future change that flips the removal policy. Flagged
-in §15.
+The protection knobs are asserted per parameter combination in
+`apps/aws-stack/tests/stack.test.ts` (the "DynamoDB table protection"
+suite).
 
 ### 9.5 TTL on `Connections.idleSince`
 
@@ -1005,12 +1093,25 @@ verify against the current AWS pricing page** before budgeting:
 | Lambda                   | GB-second                                      | $0.0000166667 (≈ $0.0167 / GB-hour) |
 | DynamoDB on-demand       | write request unit (WRU)                       | $1.25 / million               |
 | DynamoDB on-demand       | read request unit (RRU)                        | $0.25 / million               |
+| DynamoDB PITR (continuous)| GB-month of table data + indexes, per table   | ~$0.20 / GB-month             |
 | EventBridge Scheduler    | event published                                | $1.00 / million               |
 | CloudWatch Logs          | GB ingested                                    | $0.50                         |
 
 The Lambda free tier (1M requests + 400k GB-seconds per month) covers
 a meaningful slice of a small staging deployment.
 
+> **Table-protection cost.** `RemovalPolicy.RETAIN` and
+> `deletionProtection` are **free** — they are CloudFormation/DynamoDB
+> flags, not billable features. Point-in-time recovery (PITR) **is**
+> billed: continuously at ~$0.20/GB-month **per table**, charged on the
+> full table size including indexes, for as long as PITR is on. With the
+> default (`enablePitr=true`) this applies to the four state tables
+> (`Nicks`, `Services`, `ChannelMeta`, `ChannelMembers`); `Connections`
+> never carries PITR. For a small deployment these tables are tiny
+> (kilobytes to low megabytes), so the PITR line item is fractions of a
+> cent; it only becomes material if a table grows to many GB. Disable
+> with `-c enablePitr=false` on a cost-sensitive dev deploy (see §9.4).
+
 ### 11.2 Back-of-envelope: 100 concurrent users
 
 Assume a small staging deployment with 100 concurrent users, average

package/docs/AWS-TCP-Deployment.md

@@ -212,6 +212,18 @@ State lifecycle is identical to the wss path: the **sweeper** Lambda
 no-PONG. Both cover TCP connections because the `connId` lives in the
 same `Connections` table.
 
+**Per-IP new-flow rate limit.** The NLB path has no `$connect` event —
+flow establishment IS the first chunk — so the `perIpConnectionRate`
+budget is enforced inside `handleNlbStream`: the source IP (from
+`x-forwarded-for`) is counted against the same `sourceIp-connectedSince`
+GSI the wss `$connect` gate consults, and over-budget flows receive
+`429` with no row written. Only establishment is budgeted: every
+subsequent chunk of an established flow is also an invocation, and
+rate-limiting those would starve an active IRC session. The knobs are
+the shared `PER_IP_CONNECTION_RATE_MAX` / `PER_IP_CONNECTION_RATE_WINDOW_MS`
+env vars (default 5 per 60 s; see `AWS-Deployment.md` §7.8 for the
+three-layer throttling model).
+
 ---
 
 ## 7. Configuration reference
@@ -230,7 +242,11 @@ wss handler (`serverName`, `networkName`, `motd`), injected in
 - `SERVER_NAME`, `NETWORK_NAME`, `MOTD` (read by the shared
   `config-loader.ts`).
 - `MANAGEMENT_URL` — the wss stage's callback URL, so cross-connection
-  fanout reaches recipients on either transport.
+  fanout reaches recipients on either transport. The NLB handler's
+  execution role also carries `execute-api:ManageConnections` on the
+  wss stage (`stage.grantManagementApiAccess(nlbHandler)` in
+  `aws-stack.ts`, asserted by a synth-time test) — without it every
+  cross-transport `postToConnection` fails with 403.
 - `<TABLE>_TABLE` for each of the five tables (bare logical ids).
 
 The Lambda handler entry is the same file
@@ -240,7 +256,10 @@ excluded from the bundle (ships with the runtime).
 
 There are **no TCP-specific DynamoDB tables** — the existing `Connections`
 table gains a `transportBuffer` string attribute (SET when non-empty,
-REMOVE when empty) on rows whose `connectionId` starts with `nlb-`.
+REMOVE when empty) on rows whose `connectionId` starts with `nlb-`, plus
+the `sourceIp` attribute + `sourceIp-connectedSince` GSI shared with the
+wss path's per-IP admission gates (both transports stamp the flow/client
+IP at establishment).
 
 ---
 
@@ -306,6 +325,22 @@ then fanout uses `ApiGatewayManagementApi.postToConnection`, which works
 for both transports. If `MANAGEMENT_URL` is unset, `managementApi` is
 `null` and cross-connection sends are silent no-ops.
 
+The mirror-image symptom — a TCP client's messages never reaching wss
+recipients — is an IAM problem, not a push problem: the NLB handler's
+role must carry `execute-api:ManageConnections` on the wss stage
+(`stage.grantManagementApiAccess(nlbHandler)`; synth-time asserted in
+`apps/aws-stack/tests/stack.test.ts`). Without the grant the NLB
+handler's `postToConnection` calls fail with 403 and the delivery is
+silently dropped. Verify manually after a deploy:
+
+```bash
+# 1. Connect over wss (e.g. the web client) and JOIN #fanout-check.
+# 2. Connect over TLS :6697 (openssl one-liner in §11) and JOIN #fanout-check.
+# 3. PRIVMSG from the TCP side — the wss client must receive it, and vice
+#    versa. A silent drop + 403 in the IrcNlbHandler CloudWatch logs
+#    means the ManageConnections grant is missing.
+```
+
 ### 9.4 Lurkers get disconnected after a few minutes
 
 The NLB idle timeout. A receiving-only client sends no chunks, so the

package/docs/Chat-History.md

@@ -0,0 +1,55 @@
+# Chat History (`draft/chathistory`)
+
+The server implements the IRCv3 [`draft/chathistory`](https://ircv3.net/specs/extensions/chathistory)
+extension: a client that negotiates the `draft/chathistory` cap may query
+stored backlog (`LATEST` / `BEFORE` / `AFTER` / `AROUND` / `BETWEEN` /
+`TARGETS`) and receives the matching messages wrapped in a
+`BATCH chathistory <target>` frame, each replay line carrying its original
+`@time=…` and `msgid=…` tags.
+
+## Query limit ceiling
+
+Every client-supplied `limit` is **silently capped** at a deployment
+ceiling before it reaches the `MessageStore`:
+
+- `CHATHISTORY LATEST #chan * 999999999` returns at most
+  `chathistory.maxLimit` messages (default **100**) — the oversized value
+  never reaches the store, so a future higher-capacity backend cannot be
+  tricked into materializing a huge result set.
+- The cap is silent: the client receives up to the ceiling worth of
+  replay lines and no error. Requests below the ceiling pass through
+  unchanged; a request for exactly the ceiling is honored in full.
+- When the client omits the limit, the server default (50) applies —
+  also bounded by the ceiling, so a deployment that lowers
+  `chathistory.maxLimit` below 50 caps the default too.
+- A limit that is not a non-negative integer (e.g. `abc`, `-5`) is
+  rejected with `461 ERR_NEEDMOREPARAMS` (Invalid parameters), unchanged
+  by the ceiling.
+
+### Configuration
+
+| Knob                        | Default | Notes                                          |
+|-----------------------------|---------|------------------------------------------------|
+| `chathistory.maxLimit`      | `100`   | Positive integer; per-`CHATHISTORY`-query cap. |
+
+The knob lives in the server config (parsed by `ServerConfigSchema`), so
+any adapter's config source can set it:
+
+```json
+{
+  "serverName": "irc.example.com",
+  "networkName": "ExampleNet",
+  "chathistory": { "maxLimit": 250 }
+}
+```
+
+Omitting the `chathistory` section entirely inherits the default of 100.
+
+## Related
+
+- JOIN auto-playback (`chatHistoryPlaybackLimit`, default 50) is a
+  separate knob covering the backlog replayed on JOIN; see
+  `packages/irc-core/src/config.ts`.
+- `draft/read-marker` integration: `CHATHISTORY BEFORE` without an
+  explicit pivot falls back to the connection's last-read marker; see
+  `docs/PlanExtensions.md`.

package/docs/Cloudflare-Deployment-Guide.md

@@ -287,6 +287,10 @@ is the single source of truth for the Worker.
 | `SERVER_NAME`   | Server name sent in `001`/`005` numerics. **Required** — the CF config loader fails fast at boot when unset. | _No default; must be set in `wrangler.toml`._ |
 | `NETWORK_NAME`  | Network label in `005 NETWORK=…`.                  | `ServerlessIRCd`                     |
 | `MOTD_LINES`    | Message-of-the-day, `\n`-delimited.                | Welcome banner string.               |
+| `MAX_CLIENTS`   | Global live-connection cap (enforced by `CounterDO` at the edge). | schema default |
+| `MAX_CONNECTIONS_PER_IP` | Per-IP simultaneous-connection cap (in-memory admission in `ConnectionDO`). | schema default (10) |
+| `PER_IP_CONNECTION_RATE_MAX` | Per-IP upgrade rate budget — how many WebSocket upgrades one `CF-Connecting-IP` may open per sliding window. Enforced at the edge by `RateLimitDO` (429 when over budget). | schema default (5) |
+| `PER_IP_CONNECTION_RATE_WINDOW_MS` | Sliding-window length in ms for the upgrade rate budget. Setting only one half of the pair falls back to the schema default (60 000 ms) for the other. | schema default (60 000) |
 
 These are read by `ConnectionDO` via `Env` (see
 `packages/cf-adapter/src/env.ts:20` and the `serverConfig()` method in
@@ -295,7 +299,7 @@ bundle and are visible in the dashboard.
 
 ### 7.2 Durable Object bindings
 
-Three DO classes are exported from `src/worker.ts` (re-exported from
+The DO classes are exported from `src/worker.ts` (re-exported from
 `@serverless-ircd/cf-adapter`) and bound in `wrangler.toml`:
 
 | Binding name      | Class          | Owned state                                |
@@ -303,6 +307,9 @@ Three DO classes are exported from `src/worker.ts` (re-exported from
 | `CONNECTION_DO`   | `ConnectionDO` | Socket + ConnectionState + PING alarms.    |
 | `REGISTRY_DO`     | `RegistryDO`   | Nick uniqueness, nick→connId map (sharded).|
 | `CHANNEL_DO`      | `ChannelDO`    | Per-channel roster, modes, topic, fanout.  |
+| `CHANNEL_REGISTRY_DO` | `ChannelRegistryDO` | The channel-name registry (shard index). |
+| `COUNTER_DO`      | `CounterDO`    | Global live-connection counter (`maxClients` cap, TICKET-194). |
+| `RATE_LIMIT_DO`   | `RateLimitDO`  | Per-IP upgrade rate limiter — one sliding-window admission list per `CF-Connecting-IP`; the Worker edge checks the budget before forwarding an upgrade and rejects over-budget IPs with `429` (the per-IP layer of the connect throttling; runs before the `maxClients` counter so a flooding IP cannot consume global slots). |
 
 The class names in `wrangler.toml`'s `class_name` field MUST match the
 re-exports at the top of `apps/cf-worker/src/worker.ts:29`.
@@ -312,7 +319,7 @@ re-exports at the top of `apps/cf-worker/src/worker.ts:29`.
 ```toml
 [[migrations]]
 tag = "v1"
-new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO"]
+new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO", "CounterDO", "RateLimitDO"]
 ```
 
 `tag` is the migration id (string, monotonically tracked by wrangler).