serverless-ircd 0.2.0 → 0.3.0

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

@@ -6,6 +6,8 @@
  * can pin the timeline and identity space (PLAN §8 determinism rules).
  */
 
+import { caseFold } from './case-fold.js';
+
 /** Read-only wall clock, epoch milliseconds. */
 export interface Clock {
   now(): number;
@@ -192,6 +194,68 @@ export interface AccountStore {
   verify(mech: string, payload: SaslPayload): SaslResult;
 }
 
+/**
+ * One SASL PLAIN credential entry seeded into an {@link InMemoryAccountStore}.
+ * The `username` is also the canonical account name recorded on the
+ * connection for `extended-join` / `account-tag`.
+ */
+export interface SaslAccountCredential {
+  username: string;
+  password: string;
+}
+
+/**
+ * Reference in-memory {@link AccountStore} backed by a static list of PLAIN
+ * credentials seeded at construction.
+ *
+ * Mirrors the {@link InMemoryMessageStore} / {@link StaticMotdProvider}
+ * pattern: the port is synchronous, so adapters that need an async backend
+ * (D1, DynamoDB, Secrets Manager) pre-load their credentials into this store
+ * at boot. All three adapters (local-cli, CF, AWS) use this as the minimum
+ * viable `AccountStore`; a persistent variant (DynamoDB `Accounts` table, D1)
+ * is a documented follow-up that swaps in by replacing the construction call.
+ *
+ * Password comparison is constant-time to avoid the early-return timing
+ * oracle a naive `===` would expose. Only `PLAIN` is verified; any other
+ * mechanism returns failure (matching the reducer's mech gating).
+ */
+export class InMemoryAccountStore implements AccountStore {
+  private readonly creds: ReadonlyMap<string, string>;
+
+  constructor(credentials: ReadonlyArray<SaslAccountCredential>) {
+    this.creds = new Map(credentials.map((c) => [c.username, c.password]));
+  }
+
+  verify(mech: string, payload: SaslPayload): SaslResult {
+    if (mech.toUpperCase() !== 'PLAIN' || payload.kind !== 'PLAIN') {
+      return { ok: false, reason: `unsupported mechanism: ${mech}` };
+    }
+    const expected = this.creds.get(payload.username);
+    if (expected === undefined) {
+      return { ok: false, reason: 'invalid credentials' };
+    }
+    if (!constantTimeEquals(payload.password, expected)) {
+      return { ok: false, reason: 'invalid credentials' };
+    }
+    return { ok: true, account: payload.username };
+  }
+}
+
+/**
+ * Constant-time string equality. Compares every byte regardless of early
+ * mismatches so a remote attacker cannot short-circuit the comparison via a
+ * timing side-channel. Returns `false` when the lengths differ (the length
+ * is not considered secret for SASL PLAIN passwords).
+ */
+function constantTimeEquals(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
 // ============================================================================
 // Chat-history persistence (IRCv3 draft/chathistory)
 // ============================================================================
@@ -301,7 +365,7 @@ export class InMemoryMessageStore implements MessageStore {
   }
 
   record(message: StoredMessage): void {
-    const key = message.chan.toLowerCase();
+    const key = caseFold('rfc1459', message.chan);
     let arr = this.byChan.get(key);
     if (arr === undefined) {
       arr = [];
@@ -315,7 +379,7 @@ export class InMemoryMessageStore implements MessageStore {
 
   query(q: HistoryQuery): StoredMessage[] {
     if (q.limit <= 0) return [];
-    const arr = this.byChan.get(q.chan.toLowerCase());
+    const arr = this.byChan.get(caseFold('rfc1459', q.chan));
     if (arr === undefined || arr.length === 0) return [];
 
     switch (q.direction) {
@@ -335,14 +399,14 @@ export class InMemoryMessageStore implements MessageStore {
   }
 
   hasMsgid(chan: string, msgid: string): boolean {
-    const arr = this.byChan.get(chan.toLowerCase());
+    const arr = this.byChan.get(caseFold('rfc1459', chan));
     if (arr === undefined) return false;
     return arr.some((m) => m.msgid === msgid);
   }
 
   recent(chan: string, sinceMsgid: string | undefined, limit: number): StoredMessage[] {
     if (limit <= 0) return [];
-    const arr = this.byChan.get(chan.toLowerCase());
+    const arr = this.byChan.get(caseFold('rfc1459', chan));
     if (arr === undefined || arr.length === 0) return [];
     let start = 0;
     if (sinceMsgid !== undefined) {

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

@@ -25,6 +25,17 @@ export interface CloakingConfig {
   readonly cloakedSuffix?: string | undefined;
 }
 
+/**
+ * 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.
+ */
+export interface OperCred {
+  readonly user: string;
+  readonly password: string;
+}
+
 /**
  * Per-deployment server configuration. Adapters load this from a KV store
  * (CF) or Secrets Manager / SSM (AWS); the core only reads it.
@@ -53,6 +64,17 @@ export interface ServerConfig {
    * (see `serverPassword` note).
    */
   readonly cloaking?: CloakingConfig | undefined;
+  /**
+   * IRC operator credentials consulted by the `OPER` reducer. `undefined`
+   * (or an empty array) disables oper authentication entirely — an `OPER`
+   * attempt then receives `491 ERR_NOOPERHOST`.
+   *
+   * Typed `ReadonlyArray<OperCred> | undefined` to mirror Zod's `.optional()`
+   * output under `exactOptionalPropertyTypes: true`; the parsed config always
+   * supplies an array (defaulting to `[]`), so a parsed config is assignable
+   * here.
+   */
+  readonly operCreds?: ReadonlyArray<OperCred> | undefined;
   maxChannelsPerUser: number;
   maxTargetsPerCommand: number;
   maxListEntries: number;

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

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type AccountStore,
+  InMemoryAccountStore,
+  type SaslPayload,
+  type SaslResult,
+} from '../src/ports';
+
+/** Convenience: a PLAIN payload. */
+function plain(username: string, password: string): SaslPayload {
+  return { kind: 'PLAIN', username, password };
+}
+
+describe('InMemoryAccountStore — PLAIN', () => {
+  it('implements the AccountStore port', () => {
+    const store: AccountStore = new InMemoryAccountStore([
+      { username: 'alice', password: 'secret' },
+    ]);
+    expect(store).toBeDefined();
+  });
+
+  it('accepts valid PLAIN credentials and returns the account name', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('PLAIN', plain('alice', 'secret'));
+    expect(out).toEqual<SaslResult>({ ok: true, account: 'alice' });
+  });
+
+  it('rejects a wrong password', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('PLAIN', plain('alice', 'wrong'));
+    expect(out.ok).toBe(false);
+  });
+
+  it('rejects an unknown username', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('PLAIN', plain('bob', 'secret'));
+    expect(out.ok).toBe(false);
+  });
+
+  it('matches the first of several configured accounts', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'a-secret' },
+      { username: 'bob', password: 'b-secret' },
+    ]);
+    expect(store.verify('PLAIN', plain('bob', 'b-secret'))).toEqual<SaslResult>({
+      ok: true,
+      account: 'bob',
+    });
+  });
+
+  it('rejects when constructed with an empty account list', () => {
+    const store = new InMemoryAccountStore([]);
+    const out = store.verify('PLAIN', plain('alice', 'secret'));
+    expect(out.ok).toBe(false);
+  });
+
+  it('does not confuse credentials across accounts (no password cross-match)', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'a-secret' },
+      { username: 'bob', password: 'b-secret' },
+    ]);
+    // bob's password with alice's username must fail.
+    expect(store.verify('PLAIN', plain('alice', 'b-secret')).ok).toBe(false);
+  });
+});
+
+describe('InMemoryAccountStore — mechanism handling', () => {
+  it('rejects any non-PLAIN mechanism with a failure result', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('EXTERNAL', { kind: 'RAW', data: 'cert-subject' });
+    expect(out.ok).toBe(false);
+  });
+
+  it('treats the mechanism name case-insensitively for PLAIN', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('plain', plain('alice', 'secret'));
+    expect(out).toEqual<SaslResult>({ ok: true, account: 'alice' });
+  });
+});
+
+describe('InMemoryAccountStore — failure reason', () => {
+  it('returns a human-readable reason on failure', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('PLAIN', plain('alice', 'wrong'));
+    if (out.ok) throw new Error('expected failure');
+    expect(out.reason.length).toBeGreaterThan(0);
+  });
+});

package/packages/irc-core/tests/case-fold.test.ts

@@ -0,0 +1,80 @@
+import fc from 'fast-check';
+import { describe, expect, it } from 'vitest';
+import { type CaseMapping, caseFold } from '../src/case-fold';
+
+// ============================================================================
+// caseFold — rfc1459 special-character folding
+// ============================================================================
+
+describe('caseFold — rfc1459', () => {
+  it('folds [Foo] to {foo}', () => {
+    expect(caseFold('rfc1459', '[Foo]')).toBe('{foo}');
+  });
+
+  it('folds uppercase A–Z to a–z', () => {
+    expect(caseFold('rfc1459', 'ABCXYZ')).toBe('abcxyz');
+  });
+
+  it('folds the four rfc1459 specials [ \\ ] ^ to { | } ~', () => {
+    expect(caseFold('rfc1459', '[\\]^')).toBe('{|}~');
+  });
+
+  it('does not fold { | } ~ any further', () => {
+    expect(caseFold('rfc1459', '{|}~')).toBe('{|}~');
+  });
+
+  it('leaves non-folding characters unchanged', () => {
+    expect(caseFold('rfc1459', 'a1_-.#@')).toBe('a1_-.#@');
+  });
+
+  it('returns the empty string unchanged', () => {
+    expect(caseFold('rfc1459', '')).toBe('');
+  });
+});
+
+// ============================================================================
+// caseFold — ascii mapping (strict subset of rfc1459)
+// ============================================================================
+
+describe('caseFold — ascii', () => {
+  it('folds uppercase A–Z to a–z', () => {
+    expect(caseFold('ascii', 'ABCXYZ')).toBe('abcxyz');
+  });
+
+  it('does NOT fold the rfc1459 specials [ \\ ] ^', () => {
+    expect(caseFold('ascii', '[Foo]')).toBe('[foo]');
+  });
+
+  it('leaves non-folding characters unchanged', () => {
+    expect(caseFold('ascii', 'a1_-.#[]')).toBe('a1_-.#[]');
+  });
+});
+
+// ============================================================================
+// caseFold — idempotency (property test)
+// ============================================================================
+
+describe('caseFold — idempotency', () => {
+  const mappings: CaseMapping[] = ['rfc1459', 'ascii'];
+
+  for (const mapping of mappings) {
+    it(`fold(fold(s)) === fold(s) under ${mapping}`, () => {
+      const nickish = fc.stringMatching(/[\x21-\x7e]{0,16}/u);
+      fc.assert(
+        fc.property(nickish, (s) => {
+          const once = caseFold(mapping, s);
+          expect(caseFold(mapping, once)).toBe(once);
+        }),
+      );
+    });
+  }
+
+  it('rfc1459 and ascii agree on pure A–Z / a–z input', () => {
+    const alpha = fc.stringMatching(/^[A-Za-z]{1,16}$/u);
+    fc.assert(
+      fc.property(alpha, (s) => {
+        expect(caseFold('rfc1459', s)).toBe(caseFold('ascii', s));
+      }),
+    );
+  });
+});

package/packages/irc-core/tests/commands/kick.test.ts

@@ -134,6 +134,21 @@ describe('kickReducer — success', () => {
     );
   });
 
+  it('resolves the target using rfc1459 case-mapping ([ and { are equal)', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c1', 'alice', true);
+    addMember(chan, 'c2', 'foo[bar]');
+    const conn = makeConn('c1', 'alice');
+    const ctx = makeCtx(conn);
+
+    const out = kickReducer(chan, { command: 'KICK', params: ['#foo', 'FOO{BAR}'], tags: {} }, ctx);
+
+    expect(out.state.members.has('c2')).toBe(false);
+    expect(out.effects).toContainEqual<EffectType>(
+      Effect.applyChannelDelta('#foo', { memberships: [{ type: 'remove', conn: 'c2' }] }),
+    );
+  });
+
   it('updates the kicker lastSeen to ctx.clock.now()', () => {
     const chan = makeChan('#foo');
     addMember(chan, 'c1', 'alice', true);

package/packages/irc-core/tests/commands/oper.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, it } from 'vitest';
+import { matchOperCred, operReducer } from '../../src/commands/oper';
+import { Effect } from '../../src/effects';
+import type { Effect as EffectType, RawLine } from '../../src/effects';
+import { EmptyMotdProvider, FakeClock, SequentialIdFactory } from '../../src/ports';
+import { type ConnectionState, createConnection } from '../../src/state/connection';
+import { type Ctx, type ServerConfig, buildCtx } from '../../src/types';
+
+const baseServerConfig: ServerConfig = {
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  maxChannelsPerUser: 30,
+  maxTargetsPerCommand: 10,
+  maxListEntries: 50,
+  nickLen: 30,
+  channelLen: 50,
+  topicLen: 390,
+  quitMessage: 'Client Quit',
+};
+
+const serverConfigWithCreds: ServerConfig = {
+  ...baseServerConfig,
+  operCreds: [
+    { user: 'alice', password: 'secret' },
+    { user: 'bob', password: 'hunter2' },
+  ],
+};
+
+function makeCtx(state: ConnectionState, config: ServerConfig = serverConfigWithCreds): Ctx {
+  return buildCtx({
+    serverConfig: config,
+    clock: new FakeClock(5_000),
+    ids: new SequentialIdFactory(),
+    motd: EmptyMotdProvider,
+    connection: state,
+  });
+}
+
+function makeState(): ConnectionState {
+  const s = createConnection({ id: 'c1', connectedSince: 0 });
+  s.nick = 'alice';
+  s.user = 'alice';
+  s.host = 'example.com';
+  s.realname = 'Alice';
+  s.registration = 'registered';
+  return s;
+}
+
+const L = (text: string): RawLine => ({ text });
+
+const oper = (name?: string, password?: string) =>
+  ({
+    command: 'OPER',
+    params: name === undefined ? [] : password === undefined ? [name] : [name, password],
+    tags: {},
+  }) as const;
+
+describe('operReducer — successful authentication', () => {
+  it('sets userModes.oper and emits 381 RPL_YOUREOPER on matching credentials', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper('alice', 'secret'), ctx);
+
+    expect(out.state.userModes.oper).toBe(true);
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 381 alice :You are now an IRC operator')]),
+    ]);
+  });
+
+  it('matches the second configured credential pair', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper('bob', 'hunter2'), ctx);
+
+    expect(out.state.userModes.oper).toBe(true);
+  });
+
+  it('returns the same state reference (mutation permitted, no copy)', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper('alice', 'secret'), ctx);
+
+    expect(out.state).toBe(state);
+  });
+
+  it('updates connection lastSeen to ctx.clock.now()', () => {
+    const state = makeState();
+    expect(state.lastSeen).toBe(0);
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper('alice', 'secret'), ctx);
+
+    expect(out.state.lastSeen).toBe(5_000);
+  });
+
+  it('accepts a lower-case command token', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, { command: 'oper', params: ['alice', 'secret'], tags: {} }, ctx);
+
+    expect(out.state.userModes.oper).toBe(true);
+  });
+});
+
+describe('operReducer — already an operator (graceful no-op)', () => {
+  it('re-emits 381 without error when the connection is already oper', () => {
+    const state = makeState();
+    state.userModes.oper = true;
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper('alice', 'secret'), ctx);
+
+    expect(out.state.userModes.oper).toBe(true);
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 381 alice :You are now an IRC operator')]),
+    ]);
+  });
+
+  it('does not require correct credentials when already oper', () => {
+    const state = makeState();
+    state.userModes.oper = true;
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper('alice', 'wrong'), ctx);
+
+    expect(out.state.userModes.oper).toBe(true);
+    expect(out.effects.some((e) => e.tag === 'Send')).toBe(true);
+    // Critical: never a 464 for an already-oper connection.
+    for (const e of out.effects) {
+      if (e.tag === 'Send') for (const line of e.lines) expect(line.text).not.toContain(' 464 ');
+    }
+  });
+});
+
+describe('operReducer — wrong credentials', () => {
+  it('emits 464 ERR_PASSWDMISMATCH for a wrong password', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper('alice', 'wrong'), ctx);
+
+    expect(out.state.userModes.oper).toBe(false);
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 464 alice :Password Incorrect')]),
+    ]);
+  });
+
+  it('emits 464 ERR_PASSWDMISMATCH for an unknown operator name', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper('mallory', 'whatever'), ctx);
+
+    expect(out.state.userModes.oper).toBe(false);
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 464 alice :Password Incorrect')]),
+    ]);
+  });
+});
+
+describe('operReducer — no credentials configured', () => {
+  it('emits 491 ERR_NOOPERHOST when operCreds is absent', () => {
+    const state = makeState();
+    const ctx = makeCtx(state, baseServerConfig);
+
+    const out = operReducer(state, oper('alice', 'secret'), ctx);
+
+    expect(out.state.userModes.oper).toBe(false);
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 491 alice :No O-lines for your host')]),
+    ]);
+  });
+
+  it('emits 491 ERR_NOOPERHOST when operCreds is an empty array', () => {
+    const state = makeState();
+    const ctx = makeCtx(state, { ...baseServerConfig, operCreds: [] });
+
+    const out = operReducer(state, oper('alice', 'secret'), ctx);
+
+    expect(out.state.userModes.oper).toBe(false);
+    expect(out.effects.some((e) => e.tag === 'Send')).toBe(true);
+    for (const e of out.effects) {
+      if (e.tag === 'Send') for (const line of e.lines) expect(line.text).toContain(' 491 ');
+    }
+  });
+});
+
+describe('operReducer — missing parameters', () => {
+  it('emits 461 ERR_NEEDMOREPARAMS when no parameters are supplied', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper(), ctx);
+
+    expect(out.state.userModes.oper).toBe(false);
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 461 alice OPER :Not enough parameters')]),
+    ]);
+  });
+
+  it('emits 461 ERR_NEEDMOREPARAMS when only the name is supplied', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper('alice'), ctx);
+
+    expect(out.state.userModes.oper).toBe(false);
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 461 alice OPER :Not enough parameters')]),
+    ]);
+  });
+
+  it('uses "*" as the nick in 461 when the connection has no nick yet', () => {
+    const state = createConnection({ id: 'c1', connectedSince: 0 });
+    const ctx = makeCtx(state);
+
+    const out = operReducer(state, oper(), ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 461 * OPER :Not enough parameters')]),
+    ]);
+  });
+});
+
+describe('matchOperCred', () => {
+  it('returns true when a credential pair matches exactly', () => {
+    const creds = [
+      { user: 'alice', password: 'secret' },
+      { user: 'bob', password: 'hunter2' },
+    ];
+    expect(matchOperCred(creds, 'bob', 'hunter2')).toBe(true);
+  });
+
+  it('returns false when the password does not match', () => {
+    const creds = [{ user: 'alice', password: 'secret' }];
+    expect(matchOperCred(creds, 'alice', 'nope')).toBe(false);
+  });
+
+  it('returns false when no user matches', () => {
+    const creds = [{ user: 'alice', password: 'secret' }];
+    expect(matchOperCred(creds, 'mallory', 'secret')).toBe(false);
+  });
+
+  it('returns false for an empty credential list', () => {
+    expect(matchOperCred([], 'alice', 'secret')).toBe(false);
+  });
+
+  it('does a case-sensitive comparison of both fields', () => {
+    const creds = [{ user: 'alice', password: 'secret' }];
+    expect(matchOperCred(creds, 'Alice', 'secret')).toBe(false);
+    expect(matchOperCred(creds, 'alice', 'Secret')).toBe(false);
+  });
+});