@chatwarden/core 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/README.md +202 -6
  2. package/dist/src/audit.d.ts +27 -5
  3. package/dist/src/audit.d.ts.map +1 -1
  4. package/dist/src/audit.js +59 -8
  5. package/dist/src/audit.js.map +1 -1
  6. package/dist/src/chat.d.ts +48 -0
  7. package/dist/src/chat.d.ts.map +1 -1
  8. package/dist/src/chat.js +94 -10
  9. package/dist/src/chat.js.map +1 -1
  10. package/dist/src/chatwarden.d.ts +209 -12
  11. package/dist/src/chatwarden.d.ts.map +1 -1
  12. package/dist/src/chatwarden.js +77 -11
  13. package/dist/src/chatwarden.js.map +1 -1
  14. package/dist/src/crypto.d.ts +22 -0
  15. package/dist/src/crypto.d.ts.map +1 -0
  16. package/dist/src/crypto.js +193 -0
  17. package/dist/src/crypto.js.map +1 -0
  18. package/dist/src/decide.d.ts.map +1 -1
  19. package/dist/src/decide.js +2 -4
  20. package/dist/src/decide.js.map +1 -1
  21. package/dist/src/documents.d.ts +12 -2
  22. package/dist/src/documents.d.ts.map +1 -1
  23. package/dist/src/documents.js +56 -34
  24. package/dist/src/documents.js.map +1 -1
  25. package/dist/src/events.d.ts +3 -0
  26. package/dist/src/events.d.ts.map +1 -1
  27. package/dist/src/events.js.map +1 -1
  28. package/dist/src/hasher.js +2 -2
  29. package/dist/src/hasher.js.map +1 -1
  30. package/dist/src/index.d.ts +21 -12
  31. package/dist/src/index.d.ts.map +1 -1
  32. package/dist/src/index.js +11 -6
  33. package/dist/src/index.js.map +1 -1
  34. package/dist/src/ladder.d.ts +2 -0
  35. package/dist/src/ladder.d.ts.map +1 -1
  36. package/dist/src/ladder.js +1 -1
  37. package/dist/src/ladder.js.map +1 -1
  38. package/dist/src/log.d.ts +16 -0
  39. package/dist/src/log.d.ts.map +1 -1
  40. package/dist/src/log.js +34 -0
  41. package/dist/src/log.js.map +1 -1
  42. package/dist/src/notices.js +2 -2
  43. package/dist/src/notices.js.map +1 -1
  44. package/dist/src/policy.d.ts +129 -0
  45. package/dist/src/policy.d.ts.map +1 -0
  46. package/dist/src/policy.js +242 -0
  47. package/dist/src/policy.js.map +1 -0
  48. package/dist/src/profile.d.ts +120 -7
  49. package/dist/src/profile.d.ts.map +1 -1
  50. package/dist/src/profile.js +295 -7
  51. package/dist/src/profile.js.map +1 -1
  52. package/dist/src/reporting.d.ts +127 -0
  53. package/dist/src/reporting.d.ts.map +1 -0
  54. package/dist/src/reporting.js +172 -0
  55. package/dist/src/reporting.js.map +1 -0
  56. package/dist/src/reports.d.ts +80 -4
  57. package/dist/src/reports.d.ts.map +1 -1
  58. package/dist/src/reports.js +122 -8
  59. package/dist/src/reports.js.map +1 -1
  60. package/dist/src/sanctions.js +3 -3
  61. package/dist/src/sanctions.js.map +1 -1
  62. package/dist/src/staffReports.d.ts +17 -5
  63. package/dist/src/staffReports.d.ts.map +1 -1
  64. package/dist/src/staffReports.js +22 -5
  65. package/dist/src/staffReports.js.map +1 -1
  66. package/dist/src/staffViews.d.ts +138 -0
  67. package/dist/src/staffViews.d.ts.map +1 -0
  68. package/dist/src/staffViews.js +205 -0
  69. package/dist/src/staffViews.js.map +1 -0
  70. package/dist/src/strikes.js +2 -2
  71. package/dist/src/strikes.js.map +1 -1
  72. package/dist/src/subjects.js +2 -2
  73. package/dist/src/subjects.js.map +1 -1
  74. package/dist/src/team.d.ts +149 -0
  75. package/dist/src/team.d.ts.map +1 -0
  76. package/dist/src/team.js +385 -0
  77. package/dist/src/team.js.map +1 -0
  78. package/dist/src/types.d.ts +245 -4
  79. package/dist/src/types.d.ts.map +1 -1
  80. package/dist/src/types.js +5 -0
  81. package/dist/src/types.js.map +1 -1
  82. package/package.json +4 -1
  83. package/src/audit.ts +73 -9
  84. package/src/chat.ts +109 -9
  85. package/src/chatwarden.ts +279 -22
  86. package/src/crypto.ts +206 -0
  87. package/src/decide.ts +2 -4
  88. package/src/documents.ts +70 -43
  89. package/src/events.ts +10 -1
  90. package/src/hasher.ts +2 -2
  91. package/src/index.ts +110 -5
  92. package/src/ladder.ts +1 -1
  93. package/src/log.ts +37 -0
  94. package/src/notices.ts +2 -2
  95. package/src/policy.ts +288 -0
  96. package/src/profile.ts +369 -14
  97. package/src/reporting.ts +251 -0
  98. package/src/reports.ts +165 -12
  99. package/src/sanctions.ts +3 -3
  100. package/src/staffReports.ts +33 -7
  101. package/src/staffViews.ts +325 -0
  102. package/src/strikes.ts +2 -2
  103. package/src/subjects.ts +2 -2
  104. package/src/team.ts +422 -0
  105. package/src/types.ts +257 -4
package/src/chat.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { EvidenceBuffer, RoomRoster } from './evidence.js';
2
- import { safeWarn } from './log.js';
2
+ import { safeWarn, ThrottledWarn } from './log.js';
3
3
  import type { MuteService } from './mutes.js';
4
4
  import type { NoticeService } from './notices.js';
5
5
  import type { Limits } from './limits.js';
@@ -153,6 +153,19 @@ interface Restriction {
153
153
  rule: string | null;
154
154
  /** The sanction is the sender's own, not a bystander matched through a shared-IP row of another person. */
155
155
  own: boolean;
156
+ /** A full ban, a moderator's chat restriction, or an automatic one (stored or in memory). */
157
+ kind: 'chat' | 'ban' | 'auto';
158
+ }
159
+
160
+ /**
161
+ * What {@link ChatService.restricted} answers. `until` is the epoch ms the restriction ends (`null` = permanent, or
162
+ * unknown), `kind` what it is. Both are `null` when the restriction is not the person's own (a shared-IP row of
163
+ * someone else's sanction): they are restricted, and are told nothing about the other person.
164
+ */
165
+ export interface RestrictedAnswer {
166
+ restricted: boolean;
167
+ until: number | null;
168
+ kind: 'chat' | 'ban' | 'auto' | null;
156
169
  }
157
170
 
158
171
  /** Map key for a seat. NUL cannot appear in a room or seat id the way ':' can, so keys never collide. */
@@ -188,6 +201,8 @@ export class ChatService {
188
201
  private readonly autoRestrictRule: number;
189
202
  private readonly maxLength: number;
190
203
  private readonly rate: SlidingWindow;
204
+ /** The typing lookup runs at keystroke rate: its failure line is limited to one a minute. */
205
+ private readonly typingWarn: ThrottledWarn;
191
206
 
192
207
  /**
193
208
  * Automatic restrictions that could not be stored (no subject to put a row on, or the write failed), by
@@ -213,6 +228,7 @@ export class ChatService {
213
228
  this.onAutoRestrict = deps.onAutoRestrict;
214
229
  this.onAutoRestricted = deps.onAutoRestricted;
215
230
  this.logger = deps.logger;
231
+ this.typingWarn = new ThrottledWarn(deps.logger, deps.clock);
216
232
  this.notices = deps.notices;
217
233
  this.autoRestrictRule = deps.autoRestrictRule ?? DEFAULT_AUTO_RESTRICT_RULE;
218
234
  this.maxLength = deps.limits?.maxLength ?? MAX_LEN;
@@ -254,6 +270,45 @@ export class ChatService {
254
270
  }
255
271
  }
256
272
 
273
+ /**
274
+ * Is this person chat-restricted right now? For a typing indicator: show none while `restricted` is true. It runs
275
+ * the same decision as `accept` (`resolveRestriction`), and equals what `accept` would answer for the seat when
276
+ * `roomId` and `seatId` are both given. Without them the in-memory automatic timeout (the one that could not be
277
+ * stored, and every one earned by a guest with no identity) is looked up by person, over `roomId` or over every
278
+ * room, and a guest (no subject) cannot be found at all, since one guest cannot be told from another. The `gate`
279
+ * hook is not consulted: a gate refusal is not a restriction.
280
+ *
281
+ * Safe for a player's own client: it reveals nothing about others. A restriction that only reaches the person
282
+ * through a shared address of someone else's sanction reads `{ restricted: true, until: null, kind: null }`.
283
+ * Call it after the person is seated, with an identity from the platform and never one sent by the client; the
284
+ * address checked is the one the person last had recorded, as in `accept`.
285
+ *
286
+ * Synchronous and a pure read: no rate budget, nothing written, no event, no strike. It logs only a failure (event
287
+ * and error class), at most once a minute with a count of those held back; a failure reads as not restricted.
288
+ * An empty `roomId` or `seatId` counts as not given.
289
+ */
290
+ restricted(subject: SubjectId | null, roomId?: string | null, seatId?: string | null): RestrictedAnswer {
291
+ try {
292
+ const now = this.clock.now();
293
+ const room = roomId === undefined || roomId === null || roomId === '' ? null : roomId;
294
+ const seat = seatId === undefined || seatId === null || seatId === '' ? null : seatId;
295
+ const memory =
296
+ room !== null && seat !== null
297
+ ? () => this.memoryHeldAt(room, seat, subject, now, false)
298
+ : () => this.memoryHeldBy(subject, room, now);
299
+ const found = this.resolveRestriction(subject, now, memory, (err) =>
300
+ this.typingWarn.warn('chat.restriction_failed', { error: errName(err) }),
301
+ );
302
+ if (found === null) return { restricted: false, until: null, kind: null };
303
+ // Someone else's row reaching this person through a shared address: restricted, nothing more.
304
+ if (!found.own) return { restricted: true, until: null, kind: null };
305
+ return { restricted: true, until: found.until, kind: found.kind };
306
+ } catch (err) {
307
+ this.typingWarn.warn('chat.restriction_failed', { error: errName(err) });
308
+ return { restricted: false, until: null, kind: null };
309
+ }
310
+ }
311
+
257
312
  // --- internals -----------------------------------------------------------
258
313
 
259
314
  private run(roomId: string, seatId: string, text: string, opts?: { audience?: string[] }): ChatResult {
@@ -380,17 +435,61 @@ export class ChatService {
380
435
  * failure is logged and reads as "not restricted".
381
436
  */
382
437
  private activeRestriction(roomId: string, seatId: string, subject: SubjectId | null, now: number): Restriction | null {
438
+ return this.resolveRestriction(subject, now, () => this.memoryHeldAt(roomId, seatId, subject, now, true));
439
+ }
440
+
441
+ /**
442
+ * The in-memory automatic timeout on one seat: its end, or null when there is none, it is over, or the seat now holds a
443
+ * different person (two guests count as the same). The one lookup `accept` and a seat-aware `restricted` share; `sweep`
444
+ * drops an expired entry (`accept` does, a read-only lookup does not).
445
+ */
446
+ private memoryHeldAt(roomId: string, seatId: string, subject: SubjectId | null, now: number, sweep: boolean): number | null {
447
+ const key = memKey(roomId, seatId);
448
+ const mem = this.memRestrictions.get(key);
449
+ if (mem === undefined) return null;
450
+ if (mem.until <= now) {
451
+ if (sweep) this.memRestrictions.delete(key);
452
+ return null;
453
+ }
454
+ return this.samePerson(mem.subject, subject) ? mem.until : null;
455
+ }
456
+
457
+ /**
458
+ * The in-memory automatic timeout held by a known person, found without a seat (the longest, over `roomId` or over
459
+ * every room). A guest (no subject) is never matched: with no seat there is no telling one guest from another.
460
+ * Read only: an expired entry is skipped, not swept.
461
+ */
462
+ private memoryHeldBy(subject: SubjectId | null, roomId: string | null, now: number): number | null {
463
+ if (subject === null) return null;
464
+ const prefix = roomId === null ? null : memKey(roomId, '');
465
+ let best: number | null = null;
466
+ for (const [key, mem] of this.memRestrictions) {
467
+ if (mem.until <= now || mem.subject === null) continue;
468
+ if (prefix !== null && !key.startsWith(prefix)) continue;
469
+ if (best !== null && mem.until <= best) continue;
470
+ if (this.samePerson(mem.subject, subject)) best = mem.until;
471
+ }
472
+ return best;
473
+ }
474
+
475
+ /**
476
+ * THE restriction decision, shared by `accept` (a seat) and `restricted` (a person): the longest of the stored chat
477
+ * restriction, the stored full ban and the in-memory automatic one, whose end `memory` reports (null = none).
478
+ * Permanent beats timed; on a tie the stored one wins.
479
+ */
480
+ private resolveRestriction(
481
+ subject: SubjectId | null,
482
+ now: number,
483
+ memory: () => number | null,
484
+ failed: (err: unknown) => void = (err) => this.warn('chat.restriction_failed', { error: errName(err) }),
485
+ ): Restriction | null {
383
486
  try {
384
487
  // The kill switch silences the in-memory restrictions too: they are sanctions, just never stored.
385
488
  if (!this.sanctions.isEnabled()) return null;
386
- const key = memKey(roomId, seatId);
387
489
  let best: Restriction | null = null;
388
- const mem = this.memRestrictions.get(key);
389
- if (mem !== undefined) {
390
- if (mem.until <= now) this.memRestrictions.delete(key);
391
- else if (this.samePerson(mem.subject, subject)) {
392
- best = { until: mem.until, byModerator: false, groupId: null, rule: String(this.autoRestrictRule), own: true };
393
- }
490
+ const memUntil = memory();
491
+ if (memUntil !== null) {
492
+ best = { until: memUntil, byModerator: false, groupId: null, rule: String(this.autoRestrictRule), own: true, kind: 'auto' };
394
493
  }
395
494
  // Only the latest IP of a seated person is known; an IP row speed-bumps them, never links two people.
396
495
  const ids: Identifiers = {
@@ -408,12 +507,13 @@ export class ChatService {
408
507
  groupId: stored.groupId,
409
508
  rule: stored.rule,
410
509
  own: stored.own,
510
+ kind: kind === 'ban' ? 'ban' : stored.automated ? 'auto' : 'chat',
411
511
  };
412
512
  }
413
513
  }
414
514
  return best;
415
515
  } catch (err) {
416
- this.warn('chat.restriction_failed', { error: errName(err) });
516
+ failed(err);
417
517
  return null;
418
518
  }
419
519
  }