notifkit 0.1.17 → 0.1.18

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 (59) hide show
  1. package/README.md +5 -1
  2. package/dist/{bootstrap-P63acBG9.mjs → bootstrap-Cs1XIp6b.mjs} +1 -1
  3. package/dist/{bulk-Beblt3ny.mjs → bulk-4pRIiG2o.mjs} +1 -1
  4. package/dist/index.d.mts +29 -111
  5. package/dist/index.mjs +2 -2
  6. package/dist/{main-DB0bUh2r.mjs → main-BN7ZfvxN.mjs} +5 -14
  7. package/dist/{main-C3XcLoCb.mjs → main-Bl0S4GDd.mjs} +3 -3
  8. package/dist/{main-_I4b1cmP.mjs → main-C5DiM7_r.mjs} +3 -3
  9. package/dist/{main-Lcbg7aEn.mjs → main-DVzp0DLn.mjs} +8 -58
  10. package/dist/{main-NHUvynW2.mjs → main-O9iZ6iz2.mjs} +4 -9
  11. package/dist/{main-BIahf4f9.mjs → main-Ppr7Pq1g.mjs} +35 -16
  12. package/dist/{main-Dk92nti8.mjs → main-yL5VinQ5.mjs} +5 -12
  13. package/dist/{main-CktEylpL.mjs → main-zgxAlH3l.mjs} +23 -94
  14. package/dist/{schedule-or-dispatch-C5qfxQCv.mjs → schedule-or-dispatch-BwCZWS_P.mjs} +1 -1
  15. package/dist/{src-BRatuWJS.mjs → src-C38w4jR4.mjs} +61 -173
  16. package/drizzle/0009_retention_time_indexes.sql +4 -0
  17. package/drizzle/meta/_journal.json +7 -0
  18. package/package.json +1 -1
  19. package/src/client.ts +6 -6
  20. package/src/config/index.ts +8 -10
  21. package/src/contracts/sdk.ts +9 -9
  22. package/src/db/bulk.ts +3 -10
  23. package/src/db/schema.ts +3 -0
  24. package/src/idempotency/index.ts +12 -53
  25. package/src/queue/index.ts +1 -12
  26. package/src/rate-limiter/api-rate-limiter.ts +8 -27
  27. package/src/rate-limiter/project-settings-cache.ts +4 -16
  28. package/src/redis/index.ts +3 -51
  29. package/src/repositories/contact.ts +0 -2
  30. package/src/server.ts +1 -4
  31. package/src/services/api/handlers/auth.ts +3 -11
  32. package/src/services/api/handlers/campaigns.ts +4 -15
  33. package/src/services/api/handlers/events.ts +1 -2
  34. package/src/services/api/handlers/notifications.ts +6 -16
  35. package/src/services/api/handlers/projects.ts +1 -3
  36. package/src/services/api/handlers/shared.ts +7 -29
  37. package/src/services/api/handlers/system.ts +1 -1
  38. package/src/services/api/handlers/unsubscribe.ts +7 -30
  39. package/src/services/api/handlers/users.ts +1 -2
  40. package/src/services/api/http.ts +5 -10
  41. package/src/services/api/main.ts +27 -63
  42. package/src/services/api/webhooks.ts +8 -19
  43. package/src/services/auth/index.ts +2 -21
  44. package/src/services/delivery/main.ts +25 -89
  45. package/src/services/engine/main.ts +33 -69
  46. package/src/services/engine/schedule-or-dispatch.ts +7 -4
  47. package/src/services/enricher/main.ts +19 -49
  48. package/src/services/events/main.ts +3 -12
  49. package/src/services/scheduler/main.ts +26 -32
  50. package/src/services/scheduler/retention.ts +47 -0
  51. package/src/services/scheduler/send-gate.ts +6 -17
  52. package/src/services/workflow/duration.ts +1 -6
  53. package/src/services/workflow/main.ts +3 -9
  54. package/src/services/workflow/timers.ts +2 -1
  55. package/src/shared/batch-processor.ts +3 -7
  56. package/src/shared/utils.ts +2 -8
  57. package/src/transport/index.ts +0 -4
  58. package/src/unsubscribe/index.ts +3 -11
  59. package/src/workers/index.ts +8 -27
@@ -31,7 +31,7 @@ export interface Deps {
31
31
  liveEvents: LiveDeliveryEvents;
32
32
  }
33
33
 
34
- // Inline user shape (email/phone/pushToken already normalised to string[] by Zod).
34
+ // email/phone/pushToken arrive normalised to string[] by Zod.
35
35
  export interface InlineUserLike {
36
36
  id: string;
37
37
  language?: string;
@@ -53,7 +53,6 @@ interface ResolvedContact {
53
53
  preferences?: Preferences;
54
54
  }
55
55
 
56
- /** Map an inline or user input's contacts and legacy arrays into resolved contact records. */
57
56
  export function contactsOf(user: InlineUserLike): ResolvedContact[] {
58
57
  const list: ResolvedContact[] = [];
59
58
 
@@ -89,7 +88,6 @@ export function contactsOf(user: InlineUserLike): ResolvedContact[] {
89
88
  return list;
90
89
  }
91
90
 
92
- /** Persist user records + their contacts in bulk. Shared by addUser and inline notify. */
93
91
  export async function persistUsers(
94
92
  deps: Deps,
95
93
  users: InlineUserLike[],
@@ -98,9 +96,7 @@ export async function persistUsers(
98
96
  const usersList = users.map((u) => {
99
97
  const primaryEmail = u.email?.[0] ?? u.contacts?.find((c) => c.channel === "email")?.target;
100
98
 
101
- // Omitted fields stay omitted: the upsert merges what is given into the
102
- // stored profile, so an inline `{ id, phone }` on notify must not reset the
103
- // user's timezone, language or email. Defaults are applied when read.
99
+ // Omitted fields stay omitted, so an inline `{ id, phone }` keeps the stored timezone and email.
104
100
  return {
105
101
  userId: u.id,
106
102
  language: u.language,
@@ -129,12 +125,7 @@ export async function persistUsers(
129
125
  });
130
126
  }
131
127
 
132
- /**
133
- * A dead-letter entry, read the way StreamConsumer writes it: the original
134
- * event JSON under `data`, carrying a `dlq` block that records which stream it
135
- * failed on. Flat `payload`/`eventType` fields are accepted for entries written
136
- * by hand or by older versions.
137
- */
128
+ /** As StreamConsumer writes it: the event JSON under `data` with a `dlq` block. Flat fields are hand-written entries. */
138
129
  export interface DlqEntry {
139
130
  id: string;
140
131
  eventType: string;
@@ -192,10 +183,7 @@ export function parseDlqEntry(id: string, rawFields: string[]): DlqEntry {
192
183
  };
193
184
  }
194
185
 
195
- /**
196
- * Ids that live in uuid columns. Anything else can match no row, and passing it
197
- * to Postgres fails the query outright — a 500 for what is simply not found.
198
- */
186
+ /** Postgres errors on a non-uuid in a uuid column; callers answer 404 instead. */
199
187
  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
200
188
  export const isUuid = (v: string | undefined): v is string =>
201
189
  typeof v === "string" && UUID_RE.test(v);
@@ -232,26 +220,16 @@ export function decodeLogCursor(
232
220
  return null;
233
221
  }
234
222
 
235
- /**
236
- * A LIKE pattern matching `term` anywhere, with the term's own `%`, `_` and
237
- * `\` taken literally rather than as wildcards.
238
- */
223
+ /** A LIKE pattern matching `term` anywhere, its own wildcards escaped. */
239
224
  export function contains(term: string): string {
240
225
  return `%${term.replace(/[\\%_]/g, "\\$&")}%`;
241
226
  }
242
227
 
243
228
  export function getQueryParam(ctx: RouteContext, key: string): string | undefined {
244
- if (!ctx.query) return undefined;
245
- if (typeof ctx.query.get === "function") {
246
- return ctx.query.get(key) ?? undefined;
247
- }
248
- return (ctx.query as any)[key] ?? undefined;
229
+ return ctx.query.get(key) ?? undefined;
249
230
  }
250
231
 
251
- /**
252
- * Page size from `?limit=`, clamped to [1, max]. Missing or non-numeric
253
- * values fall back to `fallback`; `undefined` there means "no limit".
254
- */
232
+ /** `?limit=` clamped to [1, max]; missing or junk gives `fallback` (`undefined` = no limit). */
255
233
  export function parseLimit<F extends number | undefined>(
256
234
  ctx: RouteContext,
257
235
  fallback: F,
@@ -67,7 +67,7 @@ export function createSystemHandlers(deps: Deps) {
67
67
  });
68
68
  }
69
69
 
70
- // Helper to resolve true unconsumed backlog (consumer group lag + pending entries)
70
+ // Unconsumed backlog: consumer group lag plus pending entries.
71
71
  async function getStreamBacklog(
72
72
  redis: any,
73
73
  streamKey: string,
@@ -10,9 +10,7 @@ import { type Deps } from "./shared.js";
10
10
  export function createUnsubscribeHandlers(deps: Deps) {
11
11
  const { logger } = deps;
12
12
 
13
- // Both routes are unauthenticated: they are reached from a mail client, which
14
- // has no API key. The signed token in the URL is the credential and it
15
- // authorises exactly one thing for one address.
13
+ // Both routes are public; the signed token in the URL is the credential.
16
14
 
17
15
  function sendHtml(res: ServerResponse, status: number, body: string): void {
18
16
  res.writeHead(status, {
@@ -44,14 +42,7 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
44
42
  </head><body><h1>${escapeHtml(title)}</h1>${message}</body></html>`;
45
43
  }
46
44
 
47
- /**
48
- * GET — the page a human lands on after clicking the link in the mail body.
49
- *
50
- * Deliberately does not unsubscribe anything. Corporate mail scanners and
51
- * link prescanners issue a GET against every URL in a message; performing the
52
- * opt-out here would unsubscribe people who never clicked. The mutation lives
53
- * behind the POST.
54
- */
45
+ // GET only shows a confirm page: mail scanners GET every link in a message.
55
46
  async function unsubscribePage(
56
47
  _req: IncomingMessage,
57
48
  res: ServerResponse,
@@ -96,23 +87,14 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
96
87
  );
97
88
  }
98
89
 
99
- /**
100
- * POST — the real opt-out.
101
- *
102
- * Serves two callers with one handler: a mail client doing RFC 8058 one-click
103
- * (body `List-Unsubscribe=One-Click`, token in the query string, no
104
- * confirmation possible), and the form on the page above. Neither can carry a
105
- * CSRF token, and the one-click spec forbids an interstitial, so the signed
106
- * token is the whole of the authorisation.
107
- */
90
+ // POST serves RFC 8058 one-click and the form above. Neither can carry a CSRF
91
+ // token, so the signed token is the whole authorisation.
108
92
  async function unsubscribe(
109
93
  req: IncomingMessage,
110
94
  res: ServerResponse,
111
95
  ctx: RouteContext,
112
96
  ): Promise<void> {
113
- // The one-click POST carries `List-Unsubscribe=One-Click` as its body and
114
- // the token in the query string, so there is nothing here worth reading —
115
- // but an unread body leaves bytes on a keep-alive socket. Discard it.
97
+ // Nothing in the body is needed, but unread bytes would stay on a keep-alive socket.
116
98
  req.resume();
117
99
 
118
100
  const cfg = readBaseConfig();
@@ -148,8 +130,7 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
148
130
  const internalId = userRows[0]?.id;
149
131
 
150
132
  if (claim.topics.length > 0 && internalId) {
151
- // Scoped opt-out: silence this kind of mail and leave the rest,
152
- // including anything transactional, working.
133
+ // Scoped opt-out: transactional mail keeps working.
153
134
  await deps.db
154
135
  .insert(userTopicPreferences)
155
136
  .values(claim.topics.map((topic) => ({ userId: internalId, topic, enabled: false })))
@@ -158,9 +139,7 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
158
139
  set: { enabled: sql`excluded.enabled` },
159
140
  });
160
141
  } else {
161
- // No topic to scope to, or the user record is gone. Either way the
162
- // request has to be honoured, so fall back to suppressing the address
163
- // outright — over-honouring an unsubscribe is the safe direction.
142
+ // No topic, or the user is gone: suppress the address outright.
164
143
  await deps.db
165
144
  .insert(suppressions)
166
145
  .values({
@@ -183,8 +162,6 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
183
162
  "unsubscribe honoured",
184
163
  );
185
164
  } catch (err) {
186
- // A 5xx here means the mail client reports failure and, worse, the person
187
- // believes they have opted out when they have not.
188
165
  logger.error({ err, projectId: claim.projectId }, "unsubscribe failed to apply");
189
166
  return sendHtml(
190
167
  res,
@@ -228,8 +228,7 @@ export function createUsersHandlers(deps: Deps) {
228
228
  const contactTargets = contacts.map((c) => c.target);
229
229
  let logs: any[] = [];
230
230
  if (contactTargets.length > 0) {
231
- // One statement: fetching every task id the addresses were ever sent and
232
- // passing them back as parameters failed outright past 65,535 sends.
231
+ // A subquery, not a list of ids: Postgres caps bind parameters at 65,535.
233
232
  const sentTo = deps.db
234
233
  .select({ taskId: deliveryOutbox.taskId })
235
234
  .from(deliveryOutbox)
@@ -2,11 +2,13 @@ import type { IncomingMessage, ServerResponse } from "node:http";
2
2
  import { StringDecoder } from "node:string_decoder";
3
3
  import type { ZodError } from "zod";
4
4
 
5
+ const MAX_PAYLOAD_SIZE = 5 * 1024 * 1024;
6
+
7
+ /** The body as text, for webhook signatures that are computed over the raw bytes. */
5
8
  export async function readRawBody(req: IncomingMessage): Promise<string> {
6
9
  const raw = await new Promise<string>((resolve, reject) => {
7
10
  const chunks: Buffer[] = [];
8
11
  let totalLength = 0;
9
- const MAX_PAYLOAD_SIZE = 5 * 1024 * 1024; // 5MB limit
10
12
  req.on("data", (chunk: Buffer) => {
11
13
  totalLength += chunk.length;
12
14
  if (totalLength > MAX_PAYLOAD_SIZE) {
@@ -24,16 +26,11 @@ export async function readRawBody(req: IncomingMessage): Promise<string> {
24
26
 
25
27
  export async function readJsonBody(req: IncomingMessage): Promise<unknown> {
26
28
  return new Promise<unknown>((resolve, reject) => {
27
- // Decode chunk by chunk: avoids the Buffer.concat + toString() copy that
28
- // readRawBody pays. readRawBody is kept for webhook callers that need raw
29
- // bytes for HMAC verification. The limit counts bytes as they arrive;
30
- // counting decoded characters let multibyte text through at up to three
31
- // times the limit. StringDecoder keeps a character split across two
32
- // chunks intact.
29
+ // The limit counts bytes, not decoded characters; StringDecoder keeps a
30
+ // character split across two chunks intact.
33
31
  const decoder = new StringDecoder("utf8");
34
32
  let body = "";
35
33
  let totalLength = 0;
36
- const MAX_PAYLOAD_SIZE = 5 * 1024 * 1024;
37
34
  req.on("data", (chunk: string | Buffer) => {
38
35
  const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
39
36
  totalLength += bytes.length;
@@ -86,7 +83,6 @@ export function sendNoContent(res: ServerResponse): void {
86
83
  res.writeHead(204).end();
87
84
  }
88
85
 
89
- /** Turn a Zod error into a 400 response with field-level issues. */
90
86
  export function sendValidationError(res: ServerResponse, error: ZodError): void {
91
87
  sendJson(res, 400, {
92
88
  error: "validation_error",
@@ -94,7 +90,6 @@ export function sendValidationError(res: ServerResponse, error: ZodError): void
94
90
  });
95
91
  }
96
92
 
97
- /** A thrown HttpError short-circuits a handler with a specific status/body. */
98
93
  export class HttpError extends Error {
99
94
  constructor(
100
95
  readonly status: number,
@@ -3,7 +3,7 @@ import { loadEnv, readBaseConfig } from "@/config/index.js";
3
3
  import { createLogger } from "@/logger/index.js";
4
4
  import { RedisClient } from "@/redis/index.js";
5
5
  import { StreamProducer } from "@/queue/index.js";
6
- import { createDatabase } from "@/db/index.js";
6
+ import { createDatabase, type Db, type Sql } from "@/db/index.js";
7
7
  import {
8
8
  UserRepository,
9
9
  ContactRepository,
@@ -16,7 +16,7 @@ import {
16
16
  import { STREAMS } from "@/contracts/index.js";
17
17
  import { readJsonBody, sendJson, HttpError, extractAuthToken } from "./http.js";
18
18
  import { Router } from "./router.js";
19
- import { createHandlers } from "./handlers.js";
19
+ import { createHandlers, type Deps } from "./handlers.js";
20
20
  import { handleAdminRequest } from "./admin-static.js";
21
21
  import { RedisLiveDeliveryEvents } from "./live-events.js";
22
22
  import { createHealthHandlers } from "./health.js";
@@ -33,26 +33,21 @@ import { ApiRateLimiter } from "@/rate-limiter/index.js";
33
33
 
34
34
  export { extractAuthToken };
35
35
 
36
- /** Pub/sub channel used to drop a cached API key across every API process. */
37
36
  export const API_KEY_INVALIDATION_CHANNEL = "apikey.invalidated";
38
37
 
39
- /** Default window length in milliseconds for API rate limiting (1 minute). */
40
38
  export const API_RATE_LIMIT_WINDOW_MS = 60_000;
41
39
 
42
- // ─── Bootstrap ─────────────────────────────────────────────────────────────
43
-
44
40
  loadEnv();
45
41
  const config = readBaseConfig();
46
42
 
47
43
  let logger: ReturnType<typeof createLogger>;
48
44
  let redis: RedisClient;
49
- let sql: any;
50
- let db: any;
45
+ let sql: Sql;
46
+ let db: Db;
51
47
  let producers: Record<string, StreamProducer>;
52
- let deps: any;
53
- let h: any;
54
- // Short-TTL LRU so a hot key does not hit the DB on every request. Kept small
55
- // and invalidated on key change so a revoked key stops working promptly.
48
+ let deps: Deps;
49
+ let h: ReturnType<typeof createHandlers>;
50
+ // Revoked keys are also dropped via pub/sub, so the TTL only bounds a missed message.
56
51
  interface CachedAuthKey {
57
52
  projectId: string;
58
53
  projectRateLimitRpm: number;
@@ -68,7 +63,6 @@ let router: Router;
68
63
  let liveEvents: RedisLiveDeliveryEvents | null = null;
69
64
  let apiRateLimiter: ApiRateLimiter;
70
65
 
71
- /** Whether `token` is ADMIN_API_KEY, compared in constant time. */
72
66
  function isAdminApiKey(token: string): boolean {
73
67
  if (!config.ADMIN_API_KEY) return false;
74
68
  const expectedBuffer = Buffer.from(config.ADMIN_API_KEY);
@@ -79,21 +73,15 @@ function isAdminApiKey(token: string): boolean {
79
73
  );
80
74
  }
81
75
 
82
- /**
83
- * What a dashboard user's role may do. `admin_users.role` is free text (the
84
- * create-admin script takes any value), so only the roles known to grant
85
- * writes do; anything else, `read_only` included, is read-only.
86
- */
76
+ /** `admin_users.role` is free text, so anything but a known writer role is read-only. */
87
77
  export function sessionKeyRole(role: string): "admin" | "read_only" {
88
78
  return role === "superadmin" || role === "admin" ? "admin" : "read_only";
89
79
  }
90
80
 
91
81
  /**
92
- * Resolves the client address, given how many proxies (TRUST_PROXY) are in
93
- * front of the API. Each one appends the address it saw to X-Forwarded-For,
94
- * so the client is `trustedHops` back from the connecting peer. The leftmost
95
- * entry is the one a client can write itself, so it is used only when the
96
- * chain is shorter than the configured hops.
82
+ * Each trusted proxy appends the address it saw to X-Forwarded-For, so the
83
+ * client is `trustedHops` back from the peer. Entries further left are
84
+ * client-written.
97
85
  */
98
86
  export function getClientIp(req: IncomingMessage, trustedHops: number): string {
99
87
  const peer = req.socket.remoteAddress || "unknown";
@@ -124,8 +112,6 @@ async function handleCreateProject(req: IncomingMessage, res: ServerResponse): P
124
112
  sendJson(res, 201, { id: projectId, apiKey });
125
113
  }
126
114
 
127
- // ─── HTTP server ────────────────────────────────────────────────────────────
128
-
129
115
  let server: ReturnType<typeof createServer>;
130
116
 
131
117
  export async function startApiServer() {
@@ -270,10 +256,7 @@ export async function startApiServer() {
270
256
  server.keepAliveTimeout = 5_000;
271
257
 
272
258
  async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
273
- // Fast pathname extraction: avoid allocating a full WHATWG URL object on every
274
- // request. `new URL()` parses scheme, host, port, path, and query — most of
275
- // which we never use on the hot path. URLSearchParams is built lazily and only
276
- // materialises when a handler or the auth block actually needs it.
259
+ // URL is parsed only if something reads the query.
277
260
  const rawUrl = req.url ?? "/";
278
261
  const qIdx = rawUrl.indexOf("?");
279
262
  const pathname = qIdx === -1 ? rawUrl : rawUrl.slice(0, qIdx);
@@ -325,9 +308,7 @@ export async function startApiServer() {
325
308
 
326
309
  const isProjectManagement = pathname === "/v1/projects" || pathname.startsWith("/v1/projects/");
327
310
 
328
- // Unsubscribe is reached from a mail client, which has no API key and never
329
- // will. The signed token in the URL is the credential, and it authorises
330
- // exactly one action for one address.
311
+ // Reached from a mail client; the signed token in the URL is the credential.
331
312
  const isPublicUnsubscribe = pathname === "/v1/unsubscribe";
332
313
  const isPublicAuth = pathname === "/v1/auth/login";
333
314
 
@@ -412,16 +393,15 @@ export async function startApiServer() {
412
393
  });
413
394
  tokenHashToToken.set(tokenHash, token);
414
395
  if (tokenHashToToken.size > 2000) {
415
- // A cached token must stay findable by its hash, or revoking it
416
- // cannot evict it, so the two are dropped together.
396
+ // Cleared together so every cached token stays revocable by hash.
417
397
  tokenHashToToken.clear();
418
398
  authCache.clear();
419
399
  }
420
400
  }
421
401
  }
422
402
 
423
- // Role Check
424
- if (keyRole === "read_only") {
403
+ // Logging out only ends the caller's own session, so read-only users may.
404
+ if (keyRole === "read_only" && pathname !== "/v1/auth/logout") {
425
405
  const isMutating = req.method !== "GET" && req.method !== "OPTIONS";
426
406
  if (isMutating) {
427
407
  sendJson(res, 403, { error: "forbidden", message: "API key is read-only" });
@@ -429,19 +409,12 @@ export async function startApiServer() {
429
409
  }
430
410
  }
431
411
 
432
- // Project rate limit - In-Memory Token Leasing with Redis Sliding Window
433
- const allowed = apiRateLimiter
434
- ? await apiRateLimiter.check(projectId || "global", projectRateLimitRpm)
435
- : true;
436
-
437
- if (!allowed) {
438
- if (!res.headersSent) {
439
- res.setHeader("Retry-After", "60");
440
- sendJson(res, 429, {
441
- error: "too_many_requests",
442
- message: `Project rate limit exceeded (max ${projectRateLimitRpm} req/min)`,
443
- });
444
- }
412
+ if (!(await apiRateLimiter.check(projectId || "global", projectRateLimitRpm))) {
413
+ res.setHeader("Retry-After", "60");
414
+ sendJson(res, 429, {
415
+ error: "too_many_requests",
416
+ message: `Project rate limit exceeded (max ${projectRateLimitRpm} req/min)`,
417
+ });
445
418
  return;
446
419
  }
447
420
  } else if (isProjectManagement) {
@@ -456,8 +429,7 @@ export async function startApiServer() {
456
429
  if (token.startsWith("nk_sess_")) {
457
430
  const session = await getAdminSession(redis.native, token);
458
431
  if (session) {
459
- // Creating projects and minting keys hands out admin credentials, so
460
- // a read-only dashboard user gets to look and nothing more.
432
+ // Minting keys hands out admin credentials, so read-only sessions may only look.
461
433
  if (sessionKeyRole(session.role) === "read_only" && req.method !== "GET") {
462
434
  sendJson(res, 403, { error: "forbidden", message: "Session is read-only" });
463
435
  return;
@@ -475,10 +447,7 @@ export async function startApiServer() {
475
447
  isAdminToken = true;
476
448
  }
477
449
 
478
- // The unsubscribe routes skip the block above, and with it the per-project
479
- // rate limit — they are public by necessity. Cap them per client instead so
480
- // an open endpoint cannot be used to hammer the process. Generous, because
481
- // a shared corporate egress IP can legitimately produce a burst.
450
+ // Public, so capped per client instead of per project; generous for shared corporate IPs.
482
451
  if (isPublicUnsubscribe) {
483
452
  const clientIp = getClientIp(req, config.TRUST_PROXY);
484
453
  try {
@@ -490,14 +459,12 @@ export async function startApiServer() {
490
459
  return;
491
460
  }
492
461
  } catch (err) {
493
- // Redis being down must not stop someone unsubscribing — failing open
494
- // here is the lesser evil against a recipient who cannot opt out.
462
+ // Fail open: a recipient who cannot opt out is worse than an unthrottled endpoint.
495
463
  logger.warn({ err }, "unsubscribe rate limit unavailable — allowing request");
496
464
  }
497
465
  }
498
466
 
499
- // The login route is unauthenticated and CPU-intensive due to password hashing (scrypt).
500
- // Throttle login attempts per IP to prevent credential brute-forcing and CPU exhaustion.
467
+ // Per-IP cap against brute force; each attempt also costs a scrypt hash.
501
468
  if (isPublicAuth) {
502
469
  const clientIp = getClientIp(req, config.TRUST_PROXY);
503
470
  try {
@@ -601,8 +568,6 @@ export async function startApiServer() {
601
568
  });
602
569
  }
603
570
 
604
- // ─── Shutdown ──────────────────────────────────────────────────────────────
605
-
606
571
  export async function stopApiServer(): Promise<void> {
607
572
  logger?.info("api shutdown initiated");
608
573
  if (server) {
@@ -618,8 +583,7 @@ export async function stopApiServer(): Promise<void> {
618
583
  }
619
584
  await liveEvents?.close();
620
585
  liveEvents = null;
621
- // These are module-scoped, so a restart in the same process must not inherit
622
- // the previous instance's cached auth.
586
+ // Module-scoped, so a restart in the same process must not inherit cached auth.
623
587
  authCache = new LRUCache<string, CachedAuthKey>(1000, AUTH_CACHE_TTL_MS);
624
588
  tokenHashToToken.clear();
625
589
  if (sql) await sql.end();
@@ -1,16 +1,16 @@
1
1
  import type { IncomingMessage, ServerResponse } from "node:http";
2
2
  import { inArray } from "drizzle-orm";
3
+ import type { Db } from "@/db/index.js";
3
4
  import type { Logger } from "@/logger/index.js";
4
5
  import type { Transport } from "@/transport/index.js";
5
6
  import { messageLogs, suppressions } from "@/db/schema.js";
6
7
  import { normaliseTarget } from "@/shared/index.js";
7
8
  import { readRawBody, sendJson } from "./http.js";
8
9
 
9
- /** The POST route a provider delivers webhook events to. */
10
10
  export function createWebhookHandler(
11
11
  transport: Transport,
12
12
  channel: string,
13
- deps: { db: any; logger: Logger },
13
+ deps: { db: Db; logger: Logger },
14
14
  ) {
15
15
  const { db, logger } = deps;
16
16
  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
@@ -64,17 +64,13 @@ export function createWebhookHandler(
64
64
  if (row.providerMessageId) {
65
65
  logsToProject.set(row.providerMessageId, row.projectId);
66
66
  logsToTask.set(row.providerMessageId, row.taskId);
67
- // Inherit the campaign from the delivery this event is
68
- // about, or an open never counts toward the send that
69
- // earned it.
67
+ // So an open counts toward the campaign of the send it is about.
70
68
  logsToCampaign.set(row.providerMessageId, row.campaignId);
71
69
  }
72
70
  }
73
71
  }
74
72
 
75
- // Only record events we can attribute to a real message. An
76
- // unresolvable providerMessageId used to be written against a
77
- // zero-UUID project, which is unjoinable and leaks across tenants.
73
+ // Unattributable events are dropped: there is no project to store them under.
78
74
  const attributable = events.filter(
79
75
  (e) => e.providerMessageId && logsToProject.has(e.providerMessageId),
80
76
  );
@@ -101,14 +97,11 @@ export function createWebhookHandler(
101
97
  }
102
98
 
103
99
  if (rows.length > 0) {
104
- // Providers retry on any non-2xx, so redelivery of an event we have
105
- // already recorded must be a no-op rather than a constraint error.
100
+ // Providers redeliver on any non-2xx; a repeat must be a no-op.
106
101
  await db.insert(messageLogs).values(rows).onConflictDoNothing();
107
102
  }
108
103
 
109
- // An unsubscribe, a spam complaint, or a permanently dead
110
- // address must stop future sends — logging it is not enough.
111
- // Soft bounces are excluded: the address is still good.
104
+ // Stop future sends on unsubscribes, complaints and hard bounces (not soft ones).
112
105
  const suppressionRows = attributable
113
106
  .filter(
114
107
  (e) =>
@@ -127,8 +120,7 @@ export function createWebhookHandler(
127
120
  }));
128
121
 
129
122
  if (suppressionRows.length > 0) {
130
- // First reason wins: a later bounce should not overwrite the
131
- // record that the person actively unsubscribed.
123
+ // First reason wins: a later bounce must not hide an unsubscribe.
132
124
  await db.insert(suppressions).values(suppressionRows).onConflictDoNothing();
133
125
  logger.info(
134
126
  { channel, count: suppressionRows.length },
@@ -144,8 +136,6 @@ export function createWebhookHandler(
144
136
  e.status === "bounced"),
145
137
  ).length;
146
138
  if (unsuppressable > 0) {
147
- // Worth shouting about: the event arrived, we logged it, and
148
- // we still cannot stop mailing the person.
149
139
  logger.warn(
150
140
  { channel, count: unsuppressable },
151
141
  "suppression events carried no recipient address — transport must set WebhookEvent.recipient",
@@ -159,8 +149,7 @@ export function createWebhookHandler(
159
149
  }),
160
150
  ]);
161
151
  } catch (err) {
162
- // The detail is ours to log, not the provider's: providers keep
163
- // response bodies in their delivery logs.
152
+ // No detail in the body: providers keep response bodies in their logs.
164
153
  logger.error({ err, channel }, "webhook processing error or timeout");
165
154
  if (!res.headersSent) {
166
155
  sendJson(res, 500, { error: "internal_error" });
@@ -8,11 +8,7 @@ const scryptAsync = promisify(scrypt);
8
8
  const DEFAULT_SESSION_TTL_SECONDS = 7 * 24 * 60 * 60; // 7 days
9
9
  const SESSION_PREFIX = "notif:session:";
10
10
 
11
- /**
12
- * Pre-computed dummy hash conforming to salt(16 bytes hex):hash(64 bytes hex).
13
- * Used during authentication failure to equalize execution time and prevent
14
- * user enumeration via scrypt timing side-channels.
15
- */
11
+ /** Verified against when the user does not exist, so a miss costs as much as a wrong password. */
16
12
  export const DUMMY_PASSWORD_HASH =
17
13
  "00000000000000000000000000000000:00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000";
18
14
 
@@ -26,19 +22,13 @@ export interface AdminSession {
26
22
  expiresAt: number;
27
23
  }
28
24
 
29
- /**
30
- * Hashes a plaintext password using crypto.scrypt with a random 16-byte salt.
31
- * Returns salt and hash separated by a colon.
32
- */
25
+ /** Returns `salt:hash`, both hex. */
33
26
  export async function hashPassword(password: string): Promise<string> {
34
27
  const salt = randomBytes(16).toString("hex");
35
28
  const derivedKey = (await scryptAsync(password, salt, 64)) as Buffer;
36
29
  return `${salt}:${derivedKey.toString("hex")}`;
37
30
  }
38
31
 
39
- /**
40
- * Verifies a plaintext password against a stored salt:hash string using constant-time comparison.
41
- */
42
32
  export async function verifyPassword(password: string, storedHash: string): Promise<boolean> {
43
33
  const [salt, key] = storedHash.split(":");
44
34
  if (!salt || !key) return false;
@@ -52,9 +42,6 @@ export async function verifyPassword(password: string, storedHash: string): Prom
52
42
  return timingSafeEqual(derivedKey, keyBuffer);
53
43
  }
54
44
 
55
- /**
56
- * Creates a secure session in Redis for an authenticated admin user.
57
- */
58
45
  export async function createAdminSession(
59
46
  redis: RedisClient["native"],
60
47
  user: AdminUserRecord,
@@ -76,9 +63,6 @@ export async function createAdminSession(
76
63
  return session;
77
64
  }
78
65
 
79
- /**
80
- * Retrieves an admin session from Redis if valid and unexpired.
81
- */
82
66
  export async function getAdminSession(
83
67
  redis: RedisClient["native"],
84
68
  token: string,
@@ -99,9 +83,6 @@ export async function getAdminSession(
99
83
  }
100
84
  }
101
85
 
102
- /**
103
- * Revokes an active admin session.
104
- */
105
86
  export async function revokeAdminSession(
106
87
  redis: RedisClient["native"],
107
88
  token: string,