serverless-ircd 0.10.0 → 0.11.0

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

@@ -1,6 +1,13 @@
 import { describe, expect, it } from 'vitest';
 import type { IrcMessage } from '../src/protocol/messages';
-import { IrcParseError, MAX_INPUT_BYTES, parse } from '../src/protocol/parser';
+import {
+  IrcParseError,
+  MAX_INPUT_BYTES,
+  MAX_TAGS,
+  MAX_TAG_BYTES,
+  parse,
+  parseTags,
+} from '../src/protocol/parser';
 
 describe('parse — golden vectors', () => {
   it('parses a simple command with a channel and trailing text', () => {
@@ -125,6 +132,79 @@ describe('parse — message-tags (IRCv3)', () => {
   });
 });
 
+describe('parse — tag-map prototype hardening (magic tag keys)', () => {
+  // IRCv3 Message Tags: tag KEYS are attacker-controlled. On a map built
+  // from a plain object literal, magic keys hit `Object.prototype`
+  // accessors instead of creating own properties: `__proto__=x` invokes
+  // the prototype setter (a no-op for a string RHS — the tag is silently
+  // dropped), `toString` / `constructor` / `hasOwnProperty` become own
+  // data properties that shadow inherited methods, and even when absent,
+  // inherited members are reachable through tag lookups. The tag map must
+  // have a null prototype so every tag is an own data property and no
+  // inherited member leaks into the tag namespace.
+
+  it('keeps a `__proto__` tag as an own data property instead of invoking the setter', () => {
+    const tags = parse('@__proto__=x PRIVMSG #foo :hi').tags;
+    expect(Object.hasOwn(tags, '__proto__')).toBe(true);
+    expect(tags.__proto__).toBe('x');
+  });
+
+  it('keeps a valueless `__proto__` tag as an own property with empty-string value', () => {
+    const tags = parse('@__proto__;a=b PRIVMSG #foo :hi').tags;
+    expect(Object.hasOwn(tags, '__proto__')).toBe(true);
+    expect(tags.__proto__).toBe('');
+  });
+
+  it('builds the tag map with a null prototype', () => {
+    expect(Object.getPrototypeOf(parse('@a=b PRIVMSG #foo :hi').tags)).toBe(null);
+  });
+
+  it('exposes no inherited `toString` / `constructor` / `hasOwnProperty` when no such tag exists', () => {
+    const tags = parse('@a=b PRIVMSG #foo :hi').tags;
+    expect(tags.toString).toBeUndefined();
+    expect(tags.constructor).toBeUndefined();
+    expect(tags.hasOwnProperty).toBeUndefined();
+  });
+
+  it('does not shadow `Object.prototype.toString` on any other object after `@toString=x`', () => {
+    const tags = parse('@toString=x PRIVMSG #foo :hi').tags;
+    expect(Object.hasOwn(tags, 'toString')).toBe(true);
+    expect(tags.toString).toBe('x');
+    const unrelated = {};
+    expect(unrelated.toString()).toBe('[object Object]');
+    expect(Object.keys(unrelated)).toEqual([]);
+  });
+
+  it('round-trips every magic key as an own data property', () => {
+    const tags = parse(
+      '@__proto__=p;constructor=c;toString=t;hasOwnProperty=h PRIVMSG #foo :hi',
+    ).tags;
+    expect(Object.hasOwn(tags, '__proto__')).toBe(true);
+    expect(tags.__proto__).toBe('p');
+    expect(Object.hasOwn(tags, 'constructor')).toBe(true);
+    expect(tags.constructor).toBe('c');
+    expect(Object.hasOwn(tags, 'toString')).toBe(true);
+    expect(tags.toString).toBe('t');
+    expect(Object.hasOwn(tags, 'hasOwnProperty')).toBe(true);
+    expect(tags.hasOwnProperty).toBe('h');
+  });
+
+  it('round-trips every magic key as a valueless tag', () => {
+    const tags = parse('@__proto__;constructor;toString;hasOwnProperty PRIVMSG #foo :hi').tags;
+    expect(tags.__proto__).toBe('');
+    expect(tags.constructor).toBe('');
+    expect(tags.toString).toBe('');
+    expect(tags.hasOwnProperty).toBe('');
+  });
+
+  it('leaves every `Object.prototype` member untouched after parsing magic keys', () => {
+    parse('@__proto__=p;constructor=c;toString=t;hasOwnProperty=h PRIVMSG #foo :hi');
+    expect(Object.prototype.toString).toBeTypeOf('function');
+    expect(Object.prototype.hasOwnProperty).toBeTypeOf('function');
+    expect(Object.getPrototypeOf({})).toBe(Object.prototype);
+  });
+});
+
 describe('parse — framing tolerance', () => {
   it('strips a trailing CR LF', () => {
     expect(parse('PING :tok\r\n').params).toEqual(['tok']);
@@ -134,14 +214,89 @@ describe('parse — framing tolerance', () => {
     expect(parse('PING :tok\n').params).toEqual(['tok']);
   });
 
-  it('preserves CR/LF that appears inside the trailing param', () => {
-    // The CR/LF strip regex is anchored to the END of the line only; a CR/LF
-    // embedded in a trailing param must survive into the parsed value.
-    expect(parse('PRIVMSG #foo :a\rb').params[1]).toBe('a\rb');
+  it('preserves an embedded LF in a trailing param (CR-only hardening)', () => {
+    // The CR/LF strip regex is anchored to the END of the line only; an LF
+    // embedded in a trailing param survives into the parsed value. Bare CR
+    // used to survive too — it is now rejected outright (see the bare-CR
+    // suite below); the hardening is deliberately CR-only.
     expect(parse('PRIVMSG #foo :a\nb').params[1]).toBe('a\nb');
   });
 });
 
+describe('parse — bare CR rejection', () => {
+  // After the trailing CR/LF strip, ANY remaining CR in the body is bare by
+  // definition: a mid-line CR-LF would have split the frame at the transport
+  // layer, so a surviving CR means frame control characters are being
+  // smuggled inside message content. Each case asserts the error class AND
+  // the diagnostic message so the guard is pinned against sibling throws.
+
+  it('rejects a bare CR inside a trailing param', () => {
+    expect(() => parse('PRIVMSG #foo :hello\rworld')).toThrow(IrcParseError);
+    expect(() => parse('PRIVMSG #foo :hello\rworld')).toThrow('bare CR');
+  });
+
+  it('rejects a bare CR inside a middle param', () => {
+    expect(() => parse('PRIVMSG #fo\ro :hi')).toThrow(IrcParseError);
+    expect(() => parse('PRIVMSG #fo\ro :hi')).toThrow('bare CR');
+  });
+
+  it('rejects a bare CR that precedes a valid trailing CRLF terminator', () => {
+    expect(() => parse('PRIVMSG #foo :a\rb\r\n')).toThrow(IrcParseError);
+    expect(() => parse('PRIVMSG #foo :a\rb\r\n')).toThrow('bare CR');
+  });
+
+  it('rejects a bare CR in the tag section', () => {
+    expect(() => parse('@time=n\row PRIVMSG #foo :hi')).toThrow(IrcParseError);
+    expect(() => parse('@time=n\row PRIVMSG #foo :hi')).toThrow('bare CR');
+  });
+
+  it('rejects a bare CR in the source prefix', () => {
+    expect(() => parse(':ni\rck!u@h PRIVMSG #foo :hi')).toThrow(IrcParseError);
+    expect(() => parse(':ni\rck!u@h PRIVMSG #foo :hi')).toThrow('bare CR');
+  });
+
+  it('still accepts a line whose only CR is part of the trailing CRLF terminator', () => {
+    expect(parse('PING :tok\r\n').params).toEqual(['tok']);
+  });
+
+  it('treats a trailing bare CR (no LF) as a frame remnant and strips it', () => {
+    // The trailing strip removes the whole trailing CR/LF run, so a lone
+    // trailing CR is a terminator remnant (tolerated for sloppy framers),
+    // not body content — nothing bare survives the strip.
+    expect(parse('PING :tok\r').params).toEqual(['tok']);
+  });
+});
+
+describe('parse — tag-value control-character rejection (IRCv3 message-tags)', () => {
+  // The IRCv3 Message Tags spec forbids CR, LF and NUL in tag values — not
+  // just literally, but via their escape sequences too. The line-level bare
+  // CR guard cannot see these: the wire bytes are `\\r`, not CR, so the
+  // check must fire on the UNESCAPED value.
+
+  it('rejects a tag value whose escape sequence decodes to CR', () => {
+    expect(() => parse('@msg-id=x\\ry PRIVMSG #foo :hi')).toThrow(IrcParseError);
+    expect(() => parse('@msg-id=x\\ry PRIVMSG #foo :hi')).toThrow('tag value');
+  });
+
+  it('rejects a tag value whose escape sequence decodes to LF', () => {
+    expect(() => parse('@msg-id=x\\ny PRIVMSG #foo :hi')).toThrow(IrcParseError);
+    expect(() => parse('@msg-id=x\\ny PRIVMSG #foo :hi')).toThrow('tag value');
+  });
+
+  it('rejects a literal NUL in a tag value', () => {
+    expect(() => parse('@msg-id=x\0y PRIVMSG #foo :hi')).toThrow(IrcParseError);
+    expect(() => parse('@msg-id=x\0y PRIVMSG #foo :hi')).toThrow('tag value');
+  });
+
+  it('still accepts tag values that use only the legal escapes', () => {
+    expect(parse('@a=x\\:y\\sz\\\\w PRIVMSG #foo :hi').tags).toEqual({ a: 'x;y z\\w' });
+  });
+
+  it('still accepts a valueless tag (no value to validate)', () => {
+    expect(parse('@+away PRIVMSG #foo :hi').tags).toEqual({ '+away': '' });
+  });
+});
+
 describe('parse — malformed input', () => {
   // Each case asserts both the error class AND the diagnostic message text.
   // The message assertion is what pins the failure to the *correct* guard:
@@ -219,6 +374,23 @@ describe('parse — RFC 1459 §2.3 input line-length cap', () => {
     expect(() => parse(line)).toThrow(IrcParseError);
   });
 
+  it('rejects a multi-byte line that fits 512 UTF-16 units but exceeds 512 bytes', () => {
+    // "PRIVMSG #foo :" (14 ASCII) + 400 'é' = 414 code units, 814 UTF-8 bytes.
+    // The byte cap must see the 814, not the 414.
+    const line = `PRIVMSG #foo :${'é'.repeat(400)}`;
+    expect(line.length).toBeLessThanOrEqual(MAX_INPUT_BYTES);
+    expect(() => parse(line)).toThrow(IrcParseError);
+  });
+
+  it('accepts a multi-byte line whose UTF-8 length is exactly 512 bytes', () => {
+    // "PRIVMSG #foo :" (14 ASCII) + 249 'é' (2 bytes each) = 512 bytes in
+    // 263 code units. Byte accounting must not over-reject.
+    const body = 'é'.repeat(249);
+    const line = `PRIVMSG #foo :${body}`;
+    const parsed = parse(line);
+    expect(parsed.params).toEqual(['#foo', body]);
+  });
+
   it('reports the actual byte cap in the error message for diagnostics', () => {
     const body = 'x'.repeat(MAX_INPUT_BYTES);
     try {
@@ -229,6 +401,16 @@ describe('parse — RFC 1459 §2.3 input line-length cap', () => {
       expect((err as Error).message).toMatch(/512/u);
     }
   });
+
+  it('reports the UTF-8 byte count (not the code-unit count) in the error message', () => {
+    try {
+      parse(`PRIVMSG #foo :${'é'.repeat(400)}`);
+      expect.fail('expected parse to throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(IrcParseError);
+      expect((err as Error).message).toMatch(/814/u);
+    }
+  });
 });
 
 describe('parse — command token grammar (anchored regex)', () => {
@@ -312,3 +494,103 @@ describe('unescapeTagValue — boundary conditions', () => {
     expect(parse('@a=x\\\\ PRIVMSG #foo :hi').tags.a).toBe('x\\');
   });
 });
+
+describe('parse — IRCv3 tag count cap', () => {
+  // The IRCv3 Message Tags spec recommends at most 15 tags per message.
+  // Every tag is unescaped and (when message-tags is negotiated)
+  // re-serialized onto downstream lines, so tag count is an amplification
+  // lever, not just parse cost. These tests assert the error class AND the
+  // diagnostic message so the guard is pinned against sibling throws.
+
+  it('accepts a line with exactly 15 tags (at-limit)', () => {
+    const tags = Array.from({ length: MAX_TAGS }, (_, i) => `t${i}`);
+    const parsed = parse(`@${tags.join(';')} PRIVMSG #foo :hi`);
+    expect(Object.keys(parsed.tags)).toHaveLength(MAX_TAGS);
+  });
+
+  it('rejects a line with 16 tags', () => {
+    const tags = Array.from({ length: MAX_TAGS + 1 }, (_, i) => `t${i}`);
+    const line = `@${tags.join(';')} PRIVMSG #foo :hi`;
+    expect(() => parse(line)).toThrow(IrcParseError);
+    expect(() => parse(line)).toThrow('too many tags');
+  });
+
+  it('does not count empty tag entries toward the cap', () => {
+    // 15 real tags separated by doubled semicolons: the skipped empty
+    // entries are not tags, so the line stays at the limit.
+    const tags = Array.from({ length: MAX_TAGS }, (_, i) => `t${i}`);
+    const parsed = parse(`@${tags.join(';;')} PRIVMSG #foo :hi`);
+    expect(Object.keys(parsed.tags)).toHaveLength(MAX_TAGS);
+  });
+
+  it('reports the observed and maximum tag counts in the diagnostic', () => {
+    const tags = Array.from({ length: MAX_TAGS + 1 }, (_, i) => `t${i}`);
+    try {
+      parse(`@${tags.join(';')} PRIVMSG #foo :hi`);
+      expect.fail('expected parse to throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(IrcParseError);
+      expect((err as Error).message).toContain(`${MAX_TAGS + 1}`);
+      expect((err as Error).message).toContain(`${MAX_TAGS}`);
+    }
+  });
+});
+
+describe('parseTags — IRCv3 tag-section byte cap', () => {
+  // The IRCv3 Message Tags spec recommends a tag section of at most 8192
+  // bytes. Tested at the parseTags seam because the RFC 1459 512-byte line
+  // cap rejects any over-budget section before tags are reached — the
+  // guard holds the spec budget for parseTags callers independent of the
+  // line cap. Section here = tag data between '@' and its terminating
+  // space (both excluded).
+
+  it('accepts a tag section of exactly 8192 bytes (at-limit)', () => {
+    const section = `a=${'x'.repeat(MAX_TAG_BYTES - 2)}`;
+    const tags = parseTags(section, `@${section} PRIVMSG #foo :hi`);
+    expect(tags.a).toBe('x'.repeat(MAX_TAG_BYTES - 2));
+  });
+
+  it('rejects a tag section of 8193 bytes', () => {
+    const section = `a=${'x'.repeat(MAX_TAG_BYTES - 1)}`;
+    expect(() => parseTags(section, `@${section} PRIVMSG #foo :hi`)).toThrow(IrcParseError);
+    expect(() => parseTags(section, `@${section} PRIVMSG #foo :hi`)).toThrow('tag section exceeds');
+  });
+
+  it('measures UTF-8 bytes, not UTF-16 code units', () => {
+    // 4095 'é' after 'a=' is 4097 code units but exactly 8192 bytes →
+    // at-limit. One more 'é' crosses the byte budget while still being
+    // only ~4098 code units: byte accounting must be the binding measure.
+    const atLimit = `a=${'é'.repeat((MAX_TAG_BYTES - 2) / 2)}`;
+    expect(parseTags(atLimit, `@${atLimit} PRIVMSG #foo :hi`).a).toBe(
+      'é'.repeat((MAX_TAG_BYTES - 2) / 2),
+    );
+    const overLimit = `a=${'é'.repeat(MAX_TAG_BYTES / 2)}`;
+    expect(() => parseTags(overLimit, `@${overLimit} PRIVMSG #foo :hi`)).toThrow(
+      'tag section exceeds',
+    );
+  });
+
+  it('reports the budget and the observed byte count in the diagnostic', () => {
+    const section = `a=${'x'.repeat(MAX_TAG_BYTES - 1)}`;
+    try {
+      parseTags(section, `@${section} PRIVMSG #foo :hi`);
+      expect.fail('expected parseTags to throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(IrcParseError);
+      expect((err as Error).message).toContain(`${MAX_TAG_BYTES}`);
+      expect((err as Error).message).toContain(`${MAX_TAG_BYTES + 1}`);
+    }
+  });
+
+  it('checks the byte budget before the tag count', () => {
+    // A section violating BOTH caps reports the byte budget: the byte
+    // check is O(1) up front, the count check needs the split.
+    const entries = Array.from({ length: MAX_TAGS + 1 }, (_, i) => `t${i}=x`.padEnd(600, 'y'));
+    const section = entries.join(';');
+    expect(() => parseTags(section, `@${section} PRIVMSG #foo :hi`)).toThrow('tag section exceeds');
+  });
+
+  it('keeps the null-prototype tag map on the happy path', () => {
+    expect(Object.getPrototypeOf(parseTags('a=b', '@a=b PRIVMSG #foo :hi'))).toBe(null);
+  });
+});

package/packages/irc-core/tests/persistent-services-store.test.ts

@@ -10,6 +10,7 @@
  */
 
 import { describe, expect, it } from 'vitest';
+import { certIdentityFromSubject } from '../src/certfp';
 import {
   FakeClock,
   InMemoryServicesStore,
@@ -290,6 +291,67 @@ describe('PersistentServicesStore — per-mutator ops', () => {
     expect(s.batches).toEqual([]);
   });
 
+  it('recordIdentifyFailure → upsertNick with the recorded timestamps', async () => {
+    const clock = new FakeClock(NOW);
+    const s = new RecordingStore({ clock });
+    s.registerNick('alice', 'pw', 'a@x');
+    clock.advance(5);
+    s.recordIdentifyFailure('alice');
+    await s.flush();
+    const upserts = ops(s).filter((w) => w.kind === 'upsertNick');
+    // registerNick + recordIdentifyFailure → two upserts.
+    expect(upserts).toHaveLength(2);
+    const last = upserts[upserts.length - 1];
+    if (last?.kind === 'upsertNick') {
+      expect(last.row.identifyFailures).toEqual([NOW + 5]);
+      expect(last.row.pendingIdentifyFailureNotice).toBe(1);
+    }
+  });
+
+  it('recordIdentifyFailure on an unregistered nick enqueues nothing', async () => {
+    const s = recordingStore();
+    s.recordIdentifyFailure('ghost');
+    await s.flush();
+    expect(s.batches).toEqual([]);
+  });
+
+  it('clearIdentifyFailures on an unregistered nick enqueues nothing and returns 0', async () => {
+    const s = recordingStore();
+    expect(s.clearIdentifyFailures('ghost')).toBe(0);
+    await s.flush();
+    expect(s.batches).toEqual([]);
+  });
+
+  it('clearIdentifyFailures → upsertNick resetting the throttle state', async () => {
+    const clock = new FakeClock(NOW);
+    const s = new RecordingStore({ clock });
+    s.registerNick('alice', 'pw', 'a@x');
+    s.recordIdentifyFailure('alice');
+    await s.flush();
+    expect(s.batches).toHaveLength(1); // register + record upserts
+
+    expect(s.clearIdentifyFailures('alice')).toBe(1);
+    await s.flush();
+    // The reset MUST produce its own write-behind batch.
+    expect(s.batches).toHaveLength(2);
+    const upserts = ops(s).filter((w) => w.kind === 'upsertNick');
+    const last = upserts[upserts.length - 1];
+    if (last?.kind === 'upsertNick') {
+      expect(last.row.identifyFailures).toEqual([]);
+      expect(last.row.pendingIdentifyFailureNotice).toBe(0);
+    }
+  });
+
+  it('clearIdentifyFailures with nothing queued enqueues nothing', async () => {
+    const s = recordingStore();
+    s.registerNick('alice', 'pw', 'a@x');
+    await s.flush();
+    expect(s.batches).toHaveLength(1); // the registerNick upsert only
+    expect(s.clearIdentifyFailures('alice')).toBe(0);
+    await s.flush();
+    expect(s.batches).toHaveLength(1);
+  });
+
   it('addCertFP → upsertNick when a new subject is attached', async () => {
     const s = recordingStore();
     s.registerNick('alice', 'pw', 'a@x');
@@ -621,6 +683,85 @@ describe('PersistentServicesStore — per-mutator ops', () => {
   });
 });
 
+// ============================================================================
+// CertFP — canonical-DN / fingerprint write-behind
+// ============================================================================
+
+describe('PersistentServicesStore — CertFP ops (verifyCertFP migration / addCertFingerprint)', () => {
+  function lastNickRow(s: RecordingStore): ServicesNickRow | undefined {
+    const upserts = s.batches.flat().filter((w) => w.kind === 'upsertNick');
+    const last = upserts[upserts.length - 1];
+    return last?.kind === 'upsertNick' ? last.row : undefined;
+  }
+
+  it('verifyCertFP legacy-spelling migration re-persists the nick row', async () => {
+    const s = recordingStore();
+    s.registerNick('alice', 'pw', 'a@x');
+    s.addCertFP('alice', 'CN=alice , O=Example Inc');
+    await s.flush(); // drain the register/add writes
+    s.batches.length = 0;
+
+    const out = s.verifyCertFP(certIdentityFromSubject('O=Example Inc,CN=alice'));
+    expect(out.ok).toBe(true);
+    await s.flush();
+    expect(lastNickRow(s)?.certSubjects).toEqual(['cn=alice,o=Example Inc']);
+  });
+
+  it('verifyCertFP fingerprint pinning re-persists the nick row', async () => {
+    const s = recordingStore();
+    s.registerNick('alice', 'pw', 'a@x');
+    s.addCertFP('alice', 'CN=alice');
+    await s.flush();
+    s.batches.length = 0;
+
+    const out = s.verifyCertFP(certIdentityFromSubject('CN=alice', 'aa112233'));
+    expect(out.ok).toBe(true);
+    await s.flush();
+    expect(lastNickRow(s)?.certSubjects).toEqual(['cn=alice', 'fp:aa112233']);
+  });
+
+  it('verifyCertFP enqueues nothing when no binding changed (fingerprint arm)', async () => {
+    const s = recordingStore();
+    s.registerNick('alice', 'pw', 'a@x');
+    s.addCertFingerprint('alice', 'aa112233');
+    await s.flush();
+    s.batches.length = 0;
+
+    const out = s.verifyCertFP(certIdentityFromSubject('CN=alice', 'aa112233'));
+    expect(out.ok).toBe(true);
+    await s.flush();
+    expect(s.batches).toEqual([]);
+  });
+
+  it('verifyCertFP enqueues nothing on an unchanged canonical DN arm', async () => {
+    const s = recordingStore();
+    s.registerNick('alice', 'pw', 'a@x');
+    s.addCertFP('alice', 'cn=alice');
+    await s.flush();
+    s.batches.length = 0;
+
+    const out = s.verifyCertFP(certIdentityFromSubject('CN=alice'));
+    expect(out.ok).toBe(true);
+    await s.flush();
+    expect(s.batches).toEqual([]);
+  });
+
+  it('addCertFingerprint re-persists the nick row once per new binding', async () => {
+    const s = recordingStore();
+    s.registerNick('alice', 'pw', 'a@x');
+    await s.flush();
+    s.batches.length = 0;
+
+    expect(s.addCertFingerprint('alice', 'AA:11')).toBe(true);
+    s.addCertFingerprint('alice', 'aa11'); // normalised duplicate — no write
+    expect(s.addCertFingerprint('ghost', 'aa11')).toBe(false); // unknown nick
+    await s.flush();
+    const upserts = s.batches.flat().filter((w) => w.kind === 'upsertNick');
+    expect(upserts).toHaveLength(1);
+    expect(lastNickRow(s)?.certSubjects).toEqual(['fp:aa11']);
+  });
+});
+
 // ============================================================================
 // helpers
 // ============================================================================

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

@@ -1,4 +1,5 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
+import { certIdentityFromSubject } from '../src/certfp';
 import {
   CapturingLogger,
   type Clock,
@@ -14,6 +15,7 @@ import {
   SequentialIdFactory,
   SystemClock,
   UuidIdFactory,
+  constantTimeEquals,
 } from '../src/ports';
 
 describe('SystemClock', () => {
@@ -436,17 +438,22 @@ const _assertLogRecord: LogRecord = {
 void _assertLogRecord;
 
 describe('InMemoryMtlsIdentityProvider', () => {
-  it('returns the certificate subject for a known connection id', () => {
+  it('returns the certificate identity for a known connection id', () => {
     const provider = new InMemoryMtlsIdentityProvider([
-      { connId: 'c1', identity: 'CN=alice' },
-      { connId: 'c2', identity: 'CN=bob' },
+      { connId: 'c1', identity: certIdentityFromSubject('CN=alice') },
+      { connId: 'c2', identity: certIdentityFromSubject('CN=bob', 'ff11') },
     ]);
-    expect(provider.getIdentity('c1')).toBe('CN=alice');
-    expect(provider.getIdentity('c2')).toBe('CN=bob');
+    expect(provider.getIdentity('c1')).toEqual({
+      subject: 'CN=alice',
+      canonicalDn: 'cn=alice',
+    });
+    expect(provider.getIdentity('c2')?.fingerprint).toBe('ff11');
   });
 
   it('returns undefined for an unknown connection id', () => {
-    const provider = new InMemoryMtlsIdentityProvider([{ connId: 'c1', identity: 'CN=alice' }]);
+    const provider = new InMemoryMtlsIdentityProvider([
+      { connId: 'c1', identity: certIdentityFromSubject('CN=alice') },
+    ]);
     expect(provider.getIdentity('nope')).toBeUndefined();
   });
 
@@ -455,3 +462,88 @@ describe('InMemoryMtlsIdentityProvider', () => {
     expect(provider.getIdentity('c1')).toBeUndefined();
   });
 });
+
+// ============================================================================
+// constantTimeEquals — constant-time string equality
+// ============================================================================
+
+describe('constantTimeEquals', () => {
+  it('returns true for equal strings', () => {
+    expect(constantTimeEquals('s3cret', 's3cret')).toBe(true);
+  });
+
+  it('returns true for two empty strings', () => {
+    expect(constantTimeEquals('', '')).toBe(true);
+  });
+
+  it('returns false when the first character differs', () => {
+    expect(constantTimeEquals('X3cret', 's3cret')).toBe(false);
+  });
+
+  it('returns false when the last character differs', () => {
+    expect(constantTimeEquals('s3creX', 's3cret')).toBe(false);
+  });
+
+  it('returns false when the attempt is a proper prefix of the secret', () => {
+    expect(constantTimeEquals('s3cr', 's3cret')).toBe(false);
+  });
+
+  it('returns false when the attempt is longer than the secret', () => {
+    expect(constantTimeEquals('s3cret-extra', 's3cret')).toBe(false);
+  });
+
+  it('returns false for an empty attempt against a non-empty secret', () => {
+    expect(constantTimeEquals('', 's3cret')).toBe(false);
+  });
+
+  it('returns false for a non-empty attempt against an empty secret', () => {
+    expect(constantTimeEquals('s3cret', '')).toBe(false);
+  });
+
+  it('returns true for equal multi-byte strings', () => {
+    expect(constantTimeEquals('pässwörd', 'pässwörd')).toBe(true);
+  });
+
+  it('returns false for unequal multi-byte strings', () => {
+    expect(constantTimeEquals('pässwörd', 'password')).toBe(false);
+  });
+});
+
+// Deterministic timing-bucket proof: instead of measuring wall-clock time the
+// per-position read primitive (`charCodeAt`) is stubbed with a counter. A
+// constant-time compare reads every position of both inputs up to the longer
+// length, so the read count is identical across equal inputs, first-char
+// mismatches, last-char mismatches, and length mismatches of the same
+// magnitude — no distinguishable work bucket exists.
+describe('constantTimeEquals — timing buckets (deterministic read counts)', () => {
+  function countReads(a: string, b: string): number {
+    const spy = vi.spyOn(String.prototype, 'charCodeAt');
+    try {
+      constantTimeEquals(a, b);
+      return spy.mock.calls.length;
+    } finally {
+      spy.mockRestore();
+    }
+  }
+
+  it('reads every position of both inputs for same-length secrets (2 × length)', () => {
+    expect(countReads('s3cret', 's3cret')).toBe(12);
+    expect(countReads('X3cret', 's3cret')).toBe(12);
+    expect(countReads('s3creX', 's3cret')).toBe(12);
+    expect(countReads('s3c!et', 's3cret')).toBe(12);
+  });
+
+  it('reads the longer length even when the attempt is a length-mismatched prefix', () => {
+    expect(countReads('s3cr', 's3cret')).toBe(12);
+    expect(countReads('', 's3cret')).toBe(12);
+  });
+
+  it('reads the attempt length when the attempt is longer than the secret', () => {
+    expect(countReads('s3cret-longer', 's3cret')).toBe(26);
+    expect(countReads('X3cret-longer', 's3cret')).toBe(26);
+  });
+
+  it('spends zero reads on two empty strings', () => {
+    expect(countReads('', '')).toBe(0);
+  });
+});