serverless-ircd 0.9.0 → 0.11.0

package/packages/irc-core/src/types.ts

@@ -8,8 +8,8 @@
 
 import type { Effect } from './effects.js';
 import type { FloodControlConfig } from './flood-control.js';
+import type { OperFailureStats } from './oper-lockout.js';
 import type {
-  AccountStore,
   AwayStore,
   Clock,
   IdFactory,
@@ -53,16 +53,163 @@ export interface StsConfig {
 }
 
 /**
- * A single IRC operator credential. The {@link operReducer} consults the
- * configured list to authenticate `OPER <name> <password>`. Both fields are
- * compared verbatim; adapters are responsible for any hashing at the auth
- * boundary if they layer one on top.
+ * Legacy plaintext IRC operator credential (DEPRECATED — retained for a
+ * single deprecation-cycle window).
+ *
+ * The {@link operReducer} still verifies this shape via timing-safe byte
+ * comparison, but emits a one-shot `warn` per boot when it is encountered.
+ * Migrate to {@link OperCredHashed} via `tools/hash-oper-cred.ts`; this
+ * form will be removed in a future release.
  */
-export interface OperCred {
+export interface OperCredPlaintext {
   readonly user: string;
   readonly password: string;
 }
 
+/**
+ * At-rest hashed IRC operator credential (the recommended shape).
+ *
+ * `salt` and `hash` are base64 strings produced by
+ * `tools/hash-oper-cred.ts` (which wraps {@link hashAccountCredential}'s
+ * scrypt derivation). The {@link operReducer} verifies via the shared
+ * {@link verifyHashedPassword} with `timingSafeEqual`, mirroring the
+ * NickServ / SASL PLAIN credential path.
+ */
+export interface OperCredHashed {
+  readonly user: string;
+  readonly salt: string;
+  readonly hash: string;
+}
+
+/**
+ * A single IRC operator credential. Either the at-rest hashed form
+ * ({@link OperCredHashed}, recommended) or the legacy plaintext form
+ * ({@link OperCredPlaintext}, deprecated — retained for a single
+ * deprecation-cycle window). The {@link operReducer} consults whichever
+ * shape is present; adapters are responsible for any hashing at the auth
+ * boundary if they layer one on top.
+ */
+export type OperCred = OperCredHashed | OperCredPlaintext;
+
+/**
+ * Per-IP failed-`OPER` lockout tunables as seen by reducers. Mirrors the
+ * `oper` sub-schema of {@link ServerConfigSchema}; the OPER reducer reads
+ * `maxFailures` / `failureWindowSeconds` (falling back to the documented
+ * defaults when unset).
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true`.
+ */
+export interface OperThrottleConfig {
+  /**
+   * Consecutive failed `OPER` attempts (per host, per window) that trip
+   * the lockout. Omitted → the reducer falls back to
+   * {@link DEFAULT_OPER_MAX_FAILURES} (3).
+   */
+  readonly maxFailures?: number | undefined;
+  /**
+   * Sliding window length in seconds. Omitted → the reducer falls back to
+   * {@link DEFAULT_OPER_FAILURE_WINDOW_SECONDS} (300).
+   */
+  readonly failureWindowSeconds?: number | undefined;
+}
+
+/**
+ * NickServ-specific tunables as seen by reducers. Mirrors the
+ * `nickServ` sub-schema of {@link ServerConfigSchema}; the NickServ
+ * `SET PASSWORD` reducer reads `minPasswordLength` (falling back to
+ * {@link DEFAULT_MIN_PASSWORD_LENGTH} when unset).
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true`.
+ */
+export interface NickServConfig {
+  /**
+   * Minimum length a new password must meet to be accepted by
+   * `SET PASSWORD`. Omitted → the reducer falls back to
+   * {@link DEFAULT_MIN_PASSWORD_LENGTH} (8).
+   */
+  readonly minPasswordLength?: number | undefined;
+  /**
+   * Failed-IDENTIFY threshold that freezes the account. Omitted → the
+   * NickServ IDENTIFY reducer falls back to
+   * {@link DEFAULT_MAX_IDENTIFY_FAILURES} (5).
+   */
+  readonly maxIdentifyFailures?: number | undefined;
+  /**
+   * Sliding window (seconds) the failed-IDENTIFY threshold counts
+   * within. Omitted → the reducer falls back to
+   * {@link DEFAULT_IDENTIFY_FREEZE_SECONDS} (300).
+   */
+  readonly identifyFreezeSeconds?: number | undefined;
+}
+
+/**
+ * SASL brute-force hardening tunables as seen by reducers. Mirrors the
+ * `sasl` sub-schema of {@link ServerConfigSchema}; the SASL reducer reads
+ * them to trip a per-connection lockout after too many failed
+ * `AUTHENTICATE` attempts (falling back to the documented defaults when
+ * unset).
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true`.
+ */
+export interface SaslConfig {
+  /**
+   * Failed `AUTHENTICATE` attempts (per connection, within the sliding
+   * window) before the connection is disconnected. Omitted → the reducer
+   * falls back to {@link DEFAULT_SASL_MAX_FAILURES} (3).
+   */
+  readonly maxFailures?: number | undefined;
+  /**
+   * Sliding-window length (seconds) the failure tracker counts within.
+   * Failures older than the window no longer count. Omitted → the reducer
+   * falls back to {@link DEFAULT_SASL_FAILURE_WINDOW_SECONDS} (60).
+   */
+  readonly failureWindowSeconds?: number | undefined;
+  /**
+   * Operator opt-in for the certificate-backed SASL EXTERNAL mechanism.
+   * Omitted → EXTERNAL is neither advertised nor accepted (the reducers
+   * treat absence as `false`). Enabling additionally requires a bound
+   * mTLS identity source and a secure (TLS) connection — see the
+   * AUTHENTICATE reducer. The adapters surface this as the
+   * `EXTERNAL_ENABLED` env var.
+   */
+  readonly externalEnabled?: boolean | undefined;
+  /**
+   * Transport-level EXTERNAL non-support override. When set (by an
+   * adapter whose transport cannot surface a client-cert identity —
+   * e.g. the Spectrum PROXY-v1 TCP container origin), SASL EXTERNAL is
+   * hard-disabled for the deployment: the `sasl` cap and `908
+   * ERR_SASLMECHS` list `PLAIN` only, and `AUTHENTICATE EXTERNAL` is
+   * rejected up front with `904 ERR_SASLFAIL` carrying this exact
+   * message (a stable, transport-specific refusal) — even if
+   * {@link externalEnabled} and every three-way-gate input is bound.
+   * The rejection is a protocol-level refusal, not a credential
+   * attempt: it does not count toward the per-connection SASL failure
+   * lockout.
+   */
+  readonly externalUnsupportedMessage?: string | undefined;
+}
+
+/**
+ * `draft/chathistory` tunables as seen by reducers. Mirrors the
+ * `chathistory` sub-schema of {@link ServerConfigSchema}; the CHATHISTORY
+ * reducer caps every client-supplied query limit at `maxLimit` (falling
+ * back to {@link DEFAULT_MAX_CHATHISTORY_LIMIT} when unset).
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true`.
+ */
+export interface ChathistoryConfig {
+  /**
+   * Maximum number of messages one `CHATHISTORY` query may return.
+   * Omitted → the reducer falls back to
+   * {@link DEFAULT_MAX_CHATHISTORY_LIMIT} (100).
+   */
+  readonly maxLimit?: number | undefined;
+}
+
 /**
  * Per-deployment server configuration. Adapters load this from a KV store
  * (CF) or Secrets Manager / SSM (AWS); the core only reads it.
@@ -114,6 +261,17 @@ export interface ServerConfig {
    * here.
    */
   readonly operCreds?: ReadonlyArray<OperCred> | undefined;
+  /**
+   * Per-IP failed-`OPER` lockout tunables consulted by the `OPER`
+   * reducer's brute-force gate. Omitted (or field-omitted) values fall
+   * back to the documented defaults (3 failures / 300s window); the
+   * parsed config always supplies both fields (schema defaults).
+   *
+   * Typed `OperThrottleConfig | undefined` to mirror Zod's `.optional()`
+   * output shape under `exactOptionalPropertyTypes: true` so inline
+   * `ServerConfig` literals in tests may omit it.
+   */
+  readonly oper?: OperThrottleConfig | undefined;
   maxChannelsPerUser: number;
   maxTargetsPerCommand: number;
   maxListEntries: number;
@@ -166,6 +324,18 @@ export interface ServerConfig {
    * literals in tests may omit it.
    */
   readonly multilineMaxBytes?: number | undefined;
+  /**
+   * Per-batch entry ceiling for IRCv3 `draft/multiline`. Enforced
+   * incrementally on each accumulated inner line — together with
+   * {@link ServerConfig.multilineMaxBytes} — so a client cannot hold an
+   * unbounded batch open. Defaults to
+   * {@link DEFAULT_MULTILINE_MAX_ENTRIES} (100) when omitted.
+   *
+   * Typed `number | undefined` to mirror Zod's optional output shape under
+   * `exactOptionalPropertyTypes: true` so inline `ServerConfig` literals in
+   * tests may omit it.
+   */
+  readonly multilineMaxEntries?: number | undefined;
   /**
    * Per-connection MONITOR watchlist ceiling, advertised as `MONITOR=<n>`
    * in `005 RPL_ISUPPORT`. Omitted → the reducer falls back to
@@ -210,18 +380,71 @@ export interface ServerConfig {
    */
   readonly nickEnforceGraceMs?: number | undefined;
   /**
-   * HostServ approval mode for `REQUEST <vhost>`. `true` (the parsed
-   * default) preserves the legacy auto-approve behaviour — the vhost is
-   * recorded against the account immediately, no oper review. `false`
-   * switches HostServ into oper-queue mode: `REQUEST` queues a pending
-   * request that an oper must `APPROVE` (or `REJECT`); `LIST` enumerates
-   * the pending queue. See `docs/Services.md` §6.
+   * NickServ-specific tunables consulted by the NickServ reducer. Currently
+   * only the minimum length enforced by `SET PASSWORD` is configurable
+   * (`minPasswordLength`); the maximum (256) is fixed to bound the scrypt
+   * input budget.
+   *
+   * Typed `NickServConfig | undefined` to mirror Zod's optional output
+   * shape under `exactOptionalPropertyTypes: true` so inline
+   * `ServerConfig` literals in tests may omit it (the reducer falls back
+   * to {@link DEFAULT_MIN_PASSWORD_LENGTH} when `minPasswordLength` is
+   * unset).
+   */
+  readonly nickServ?: NickServConfig | undefined;
+  /**
+   * SASL brute-force hardening tunables consulted by the SASL reducer:
+   * `maxFailures` failed `AUTHENTICATE` attempts within
+   * `failureWindowSeconds` disconnect the connection. Omitted entirely →
+   * the reducer falls back to the documented defaults (3 failures / 60 s).
+   *
+   * Typed `SaslConfig | undefined` to mirror Zod's `.optional()` output
+   * under `exactOptionalPropertyTypes: true` so inline `ServerConfig`
+   * literals in tests may omit it.
+   */
+  readonly sasl?: SaslConfig | undefined;
+  /**
+   * `draft/chathistory` tunables consulted by the CHATHISTORY reducer.
+   * Every client-supplied query limit is silently capped at
+   * `maxLimit`; omitted entirely → the documented default ceiling (100).
+   *
+   * Typed `ChathistoryConfig | undefined` to mirror Zod's `.optional()`
+   * output shape under `exactOptionalPropertyTypes: true` so inline
+   * `ServerConfig` literals in tests may omit it.
+   */
+  readonly chathistory?: ChathistoryConfig | undefined;
+  /**
+   * HostServ approval mode for `REQUEST <vhost>`. `false` (the parsed
+   * default) is oper-queue mode: `REQUEST` queues a pending request that an
+   * oper must `APPROVE` (or `REJECT`); `LIST` enumerates the pending
+   * queue — the recommended mode. `true` preserves the legacy
+   * auto-approve behaviour (the vhost is recorded immediately, no oper
+   * review), hard-constrained by {@link hostservAutoApproveAllowlist} and
+   * a built-in denylist (reserved labels + this server's own hostname).
+   *
+   * @deprecated Auto-approve is deprecated; queue mode (the default) is
+   *   the long-term path and a future release removes the auto-approve
+   *   arm. See `docs/Services.md`.
    *
    * Typed `boolean | undefined` so inline `ServerConfig` literals in tests
-   * may omit it (the reducer treats `undefined` as "auto-approve on",
-   * matching the parsed default).
+   * may omit it (the reducer treats `undefined` as queue mode, matching
+   * the parsed default).
    */
   readonly hostservAutoApproveVhosts?: boolean | undefined;
+  /**
+   * Explicit allowlist constraining auto-approved vhosts when
+   * {@link hostservAutoApproveVhosts} is `true`: an entry is an exact
+   * hostname (`users.example.com`) or a wildcard suffix
+   * (`*.users.example.com`, any depth beneath it). Case-insensitive.
+   * Ignored in queue mode (opers vet requests). The parsed config always
+   * supplies an array (default `[]`), and config parsing refuses to boot
+   * auto-approve mode with an empty allowlist; the reducer additionally
+   * fails closed when the field is omitted from an inline literal.
+   *
+   * Typed `ReadonlyArray<string> | undefined` to mirror Zod's `.optional()`
+   * output under `exactOptionalPropertyTypes: true`.
+   */
+  readonly hostservAutoApproveAllowlist?: ReadonlyArray<string> | undefined;
 }
 
 /** Per-invocation context handed to every reducer. */
@@ -235,8 +458,6 @@ export interface Ctx {
   readonly ids: IdFactory;
   /** Pre-loaded MOTD source for the `MOTD` reducer. */
   readonly motd: MotdProvider;
-  /** SASL account verification source (absent when no accounts are configured). */
-  readonly accounts?: AccountStore;
   /**
    * mTLS client-cert identity source for SASL EXTERNAL (absent when mTLS
    * is not configured). When present, `AUTHENTICATE EXTERNAL` resolves the
@@ -280,13 +501,30 @@ export interface Ctx {
    * marker via {@link ServicesStore.setLastReadMarker}, SASL identify seeds
    * the connection's `lastReadMarkers` from
    * {@link ServicesStore.listReadMarkers} so a reconnect restores the user's
-   * read position, and SASL PLAIN falls back to this store for nicks
-   * registered via NickServ. Omitted (→ `ctx.services` undefined) preserves
-   * the no-services behaviour: `PRIVMSG NickServ :…` is not intercepted,
-   * read-marker persistence stays session-only, and SASL PLAIN consults
-   * only {@link Ctx.accounts}.
+   * read position, SASL PLAIN consults `services.verifyNick`, SASL EXTERNAL
+   * consults `services.verifyCertFP`, and PASS-based account auth
+   * (`PASS <nick>:<password>`) consults `services.verifyNick`. Omitted (→
+   * `ctx.services` undefined) preserves the no-services behaviour:
+   * `PRIVMSG NickServ :…` is not intercepted, read-marker persistence stays
+   * session-only, and every SASL/PASS credential verify fails with
+   * `904` / silent no-op.
    */
   readonly services?: ServicesStore;
+  /**
+   * Per-IP failed-`OPER` counter (absent when the deployment's runtime
+   * does not maintain one). When present, the OPER reducer counts
+   * credential failures per source host: once
+   * `serverConfig.oper.maxFailures` failures land within
+   * `serverConfig.oper.failureWindowSeconds`, further OPER attempts from
+   * that host are rejected with `491 ERR_NOOPERHOST` without consulting
+   * the credential store, and a `BroadcastOperNotice` effect notifies
+   * every oper. A successful OPER resets the host's counter. Omitted (→
+   * `ctx.operFailures` undefined) preserves the unlocked behaviour for
+   * runtimes that have not wired the shared tracker (e.g. per-connection
+   * Durable Object adapters): every attempt still reaches the credential
+   * store.
+   */
+  readonly operFailures?: OperFailureStats;
   /** The connection invoking the command. Reducers mutate this freely. */
   readonly connection: ConnectionState;
   /** Convenience: `connection.id`. */
@@ -323,12 +561,17 @@ export interface BuildCtxOptions {
   clock: Clock;
   ids: IdFactory;
   motd: MotdProvider;
-  accounts?: AccountStore;
   mtlsIdentity?: MtlsIdentityProvider;
   messages?: MessageStore;
   history?: NickHistoryStore;
   away?: AwayStore;
   services?: ServicesStore;
+  /**
+   * Per-IP failed-`OPER` counter shared across every connection (see
+   * {@link Ctx.operFailures}). Omitted → the OPER brute-force gate is
+   * disabled for this actor.
+   */
+  operFailures?: OperFailureStats;
   connection: ConnectionState;
   /**
    * IRCv3 `labeled-response` label extracted from the inbound `+label` tag.
@@ -349,12 +592,12 @@ export function buildCtx(opts: BuildCtxOptions): Ctx {
     motd: opts.motd,
     connection: opts.connection,
     connId: opts.connection.id,
-    ...(opts.accounts !== undefined ? { accounts: opts.accounts } : {}),
     ...(opts.mtlsIdentity !== undefined ? { mtlsIdentity: opts.mtlsIdentity } : {}),
     ...(opts.messages !== undefined ? { messages: opts.messages } : {}),
     ...(opts.history !== undefined ? { history: opts.history } : {}),
     ...(opts.away !== undefined ? { away: opts.away } : {}),
     ...(opts.services !== undefined ? { services: opts.services } : {}),
+    ...(opts.operFailures !== undefined ? { operFailures: opts.operFailures } : {}),
     ...(opts.label !== undefined ? { label: opts.label } : {}),
   };
   return ctx;

package/packages/irc-core/src/ws-framing.ts

@@ -25,6 +25,7 @@
  * every WebSocket runtime (Node `ws`, Cloudflare Durable Objects, Lambda).
  */
 
+import { byteLength } from './protocol/bytes.js';
 import type { WsSubprotocol } from './ws-subprotocol.js';
 
 /**
@@ -103,12 +104,12 @@ export function frameToLines(frame: string, mode: WsFrameMode): string[] {
 /**
  * Returns `true` when `frame` fits within the IRCv3 WebSocket 510-byte
  * message budget, `false` when it exceeds it and MUST be rejected by the
- * inbound path. Measured in UTF-16 code units, consistent with how
- * {@link enforceLineLimit} and the input parser cap line length across this
- * package (every supported runtime exposes `.length`).
+ * inbound path. Measured in UTF-8 bytes (the wire encoding), consistent
+ * with how {@link enforceLineLimit} and the input parser cap line length
+ * across this package, so multi-byte content cannot double the budget.
  */
 export function isWithinWsByteBudget(frame: string): boolean {
-  return frame.length <= MAX_WS_MESSAGE_BYTES;
+  return byteLength(frame) <= MAX_WS_MESSAGE_BYTES;
 }
 
 /**

package/packages/irc-core/tests/account-migration.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type LegacyAccountRow,
+  buildMigrationSql,
+  buildServicesPutItem,
+  parseSaslAccountsForMigration,
+} from '../src/account-migration';
+
+describe('parseSaslAccountsForMigration', () => {
+  it('returns an empty array for undefined', () => {
+    expect(parseSaslAccountsForMigration(undefined)).toEqual([]);
+  });
+
+  it('returns an empty array for an empty string', () => {
+    expect(parseSaslAccountsForMigration('')).toEqual([]);
+  });
+
+  it('parses a single username:password entry', () => {
+    expect(parseSaslAccountsForMigration('alice:s3cret')).toEqual([
+      { username: 'alice', password: 's3cret' },
+    ]);
+  });
+
+  it('skips blank lines and malformed entries', () => {
+    expect(
+      parseSaslAccountsForMigration('alice:s3cret\n\nnocolon\n:emptyuser\nemptypass:\n   \n'),
+    ).toEqual([{ username: 'alice', password: 's3cret' }]);
+  });
+});
+
+describe('buildMigrationSql', () => {
+  const legacyRow = (account: string, salt = 'salt', hash = 'hash'): LegacyAccountRow => ({
+    account,
+    algorithm: 'scrypt',
+    salt,
+    hash,
+  });
+
+  it('creates a nickserv_accounts row with cert_subjects "[]" for a legacy account', () => {
+    const stmts = buildMigrationSql([legacyRow('alice')], undefined);
+    expect(stmts[0]).toContain('CREATE TABLE IF NOT EXISTS nickserv_accounts');
+    expect(stmts[1]).toContain('INSERT OR IGNORE');
+    expect(stmts[1]).toContain("'alice'");
+    expect(stmts[1]).toContain("'[]'");
+  });
+
+  it('uses INSERT OR IGNORE (never REPLACE)', () => {
+    const stmts = buildMigrationSql([legacyRow('alice')], undefined);
+    expect(stmts[1]).toContain('INSERT OR IGNORE');
+    expect(stmts[1]).not.toContain('INSERT OR REPLACE');
+  });
+
+  it('is idempotent (same input → same output)', () => {
+    const stmts1 = buildMigrationSql([legacyRow('alice')], undefined);
+    const stmts2 = buildMigrationSql([legacyRow('alice')], undefined);
+    expect(stmts1).toEqual(stmts2);
+  });
+
+  it('carries SASL_ACCOUNTS env-seed entries not in the legacy table', () => {
+    const stmts = buildMigrationSql([legacyRow('alice')], 'bob:bobspw\nalice:alicespw');
+    expect(stmts).toHaveLength(3);
+    expect(stmts[1]).toContain("'alice'");
+    expect(stmts[1]).toContain("'salt'");
+    expect(stmts[2]).toContain("'bob'");
+    expect(stmts[2]).not.toContain("'bobspw'");
+  });
+
+  it('does not re-hash legacy rows', () => {
+    const stmts = buildMigrationSql([legacyRow('alice', 'mysalt', 'myhash')], undefined);
+    expect(stmts[1]).toContain("'mysalt'");
+    expect(stmts[1]).toContain("'myhash'");
+  });
+
+  it('produces only CREATE TABLE when both inputs are empty', () => {
+    const stmts = buildMigrationSql([], undefined);
+    expect(stmts).toHaveLength(1);
+  });
+
+  it('escapes single quotes in usernames', () => {
+    const stmts = buildMigrationSql([legacyRow("O'Brien")], undefined);
+    expect(stmts[1]).toContain("'O''Brien'");
+  });
+});
+
+describe('buildServicesPutItem', () => {
+  it('targets the NICK:<fold> partition', () => {
+    const input = buildServicesPutItem(
+      { account: 'alice', algorithm: 'scrypt', salt: 's', hash: 'h' },
+      'StagingServices',
+    );
+    expect(input.TableName).toBe('StagingServices');
+    expect(input.Item.pk).toBe('NICK:alice');
+    expect(input.Item.sk).toBe('#');
+    expect(input.Item.type).toBe('nick');
+  });
+
+  it('preserves the legacy scrypt credential fields', () => {
+    const input = buildServicesPutItem(
+      { account: 'alice', algorithm: 'scrypt', salt: 'mysalt', hash: 'myhash' },
+      'Services',
+    );
+    expect(input.Item.algorithm).toBe('scrypt');
+    expect(input.Item.salt).toBe('mysalt');
+    expect(input.Item.hash).toBe('myhash');
+  });
+
+  it('defaults certSubjects to an empty array', () => {
+    const input = buildServicesPutItem(
+      { account: 'alice', algorithm: 'scrypt', salt: 's', hash: 'h' },
+      'Services',
+    );
+    expect(input.Item.certSubjects).toEqual([]);
+  });
+
+  it('folds the nick case-insensitively', () => {
+    const input = buildServicesPutItem(
+      { account: 'Alice', algorithm: 'scrypt', salt: 's', hash: 'h' },
+      'Services',
+    );
+    expect(input.Item.pk).toBe('NICK:alice');
+    expect(input.Item.nick).toBe('Alice');
+  });
+
+  it('stamps default email / enforce / createdAt', () => {
+    const input = buildServicesPutItem(
+      { account: 'alice', algorithm: 'scrypt', salt: 's', hash: 'h' },
+      'Services',
+    );
+    expect(input.Item.email).toBe('');
+    expect(input.Item.enforce).toBe('none');
+    expect(input.Item.createdAt).toBe(0);
+  });
+});

package/packages/irc-core/tests/bytes.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import { byteLength, truncateToByteBudget } from '../src/protocol/bytes';
+
+// ============================================================================
+// byteLength — UTF-8 byte accounting for IRC wire budgets
+//
+// IRC line limits are byte budgets (RFC 1459 §2.3), but JavaScript strings
+// expose UTF-16 code units via `.length`. These tests pin the semantics the
+// line-budget seams rely on: one byte per ASCII char, 2–4 bytes per
+// non-ASCII code point.
+// ============================================================================
+
+describe('byteLength', () => {
+  it('returns 0 for the empty string', () => {
+    expect(byteLength('')).toBe(0);
+  });
+
+  it('counts one byte per ASCII character (matches .length)', () => {
+    expect(byteLength('NICK bob')).toBe('NICK bob'.length);
+  });
+
+  it('counts 2 bytes for a 2-byte BMP character (é)', () => {
+    expect('é'.length).toBe(1);
+    expect(byteLength('é')).toBe(2);
+  });
+
+  it('returns 1022 for 511 é characters — not the UTF-16 count of 511', () => {
+    const s = 'é'.repeat(511);
+    expect(s.length).toBe(511);
+    expect(byteLength(s)).toBe(1022);
+  });
+
+  it('counts 4 bytes for an astral code point (surrogate pair)', () => {
+    const emoji = '😀';
+    expect(emoji.length).toBe(2);
+    expect(byteLength(emoji)).toBe(4);
+  });
+
+  it('accounts for mixed ASCII and multi-byte content', () => {
+    expect(byteLength('aé😀')).toBe(1 + 2 + 4);
+  });
+});
+
+// ============================================================================
+// truncateToByteBudget — byte-bounded right-truncation
+//
+// Line-budget seams must not only DETECT over-budget multi-byte lines, they
+// must emit output that fits the byte budget. Code-unit slicing cannot do
+// that (510 'é' units = 1020 bytes) and can split surrogate pairs.
+// ============================================================================
+
+describe('truncateToByteBudget', () => {
+  it('returns the input unchanged when it already fits the budget', () => {
+    expect(truncateToByteBudget('NICK bob', 510)).toBe('NICK bob');
+  });
+
+  it('truncates ASCII input exactly like code-unit slicing', () => {
+    expect(truncateToByteBudget('x'.repeat(600), 510)).toBe('x'.repeat(510));
+  });
+
+  it('truncates multi-byte input so the result fits the byte budget', () => {
+    const out = truncateToByteBudget('é'.repeat(600), 510);
+    expect(byteLength(out)).toBeLessThanOrEqual(510);
+    // 510 bytes of 'é' = 255 chars; the budget is fully used.
+    expect(out).toBe('é'.repeat(255));
+  });
+
+  it('stops before the code point that would cross the budget', () => {
+    // Budget 511 with 'é' (2 bytes each): 255 chars = 510 bytes; the 256th
+    // 'é' would make 512, so it is dropped and one byte stays unused.
+    expect(truncateToByteBudget('é'.repeat(600), 511)).toBe('é'.repeat(255));
+  });
+
+  it('never splits a surrogate pair', () => {
+    const out = truncateToByteBudget('😀'.repeat(400), 510);
+    // 4-byte emoji: floor(510/4) = 127 complete pairs = 508 bytes.
+    expect(out).toBe('😀'.repeat(127));
+    expect(byteLength(out)).toBe(508);
+  });
+
+  it('accounts for mixed ASCII and multi-byte content', () => {
+    // 'ab' (2 bytes) + 3 'é' (6 bytes) = 8 bytes; budget 5 keeps 'abé'.
+    expect(truncateToByteBudget('abééé', 5)).toBe('abé');
+  });
+
+  it('returns the empty string for a zero budget', () => {
+    expect(truncateToByteBudget('abc', 0)).toBe('');
+  });
+});