notifkit 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notifkit",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Self-hosted notification infrastructure. One call delivers to email, SMS, push, and webhook — routed by preference, quiet hours, and consent.",
   "license": "MIT",
   "author": "devkitshq",

package/scripts/create-admin.mjs

@@ -3,8 +3,9 @@
  * Create or update an admin user for the Notifkit Dashboard.
  *
  * Usage:
- *   ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=secret node scripts/create-admin.mjs
- *   node scripts/create-admin.mjs admin@example.com secret [username] [role]
+ *   ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=secret npx notifkit-create-admin
+ *   npx notifkit-create-admin admin@example.com secret [role]
+ *   node scripts/create-admin.mjs admin@example.com secret [role]
  */
 
 import { config } from "dotenv";
@@ -25,11 +26,10 @@ async function hashPassword(password) {
 
 const email = process.argv[2] || process.env.ADMIN_EMAIL;
 const password = process.argv[3] || process.env.ADMIN_PASSWORD;
-const username = process.argv[4] || process.env.ADMIN_USERNAME || null;
-const role = process.argv[5] || "admin";
+const role = process.argv[4] || "admin";
 
 if (!email || !password) {
-  console.error("Usage: node scripts/create-admin.mjs <email> <password> [username] [role]");
+  console.error("Usage: npx notifkit-create-admin <email> <password> [role]");
   console.error("Or set ADMIN_EMAIL and ADMIN_PASSWORD in environment.");
   process.exit(1);
 }
@@ -41,23 +41,20 @@ const sql = postgres(databaseUrl);
 try {
   const passwordHash = await hashPassword(password);
   const normalizedEmail = email.trim().toLowerCase();
-  const normalizedUsername = username ? username.trim() : null;
 
   const rows = await sql`
-    INSERT INTO admin_users (email, username, password_hash, role)
-    VALUES (${normalizedEmail}, ${normalizedUsername}, ${passwordHash}, ${role})
+    INSERT INTO admin_users (email, password_hash, role)
+    VALUES (${normalizedEmail}, ${passwordHash}, ${role})
     ON CONFLICT (email) DO UPDATE
     SET password_hash = EXCLUDED.password_hash,
-        username = COALESCE(EXCLUDED.username, admin_users.username),
         role = EXCLUDED.role,
         updated_at = NOW()
-    RETURNING id, email, username, role, created_at, updated_at
+    RETURNING id, email, role, created_at, updated_at
   `;
 
   console.log("\nAdmin user successfully saved:\n");
   console.log(`  ID:       ${rows[0].id}`);
   console.log(`  Email:    ${rows[0].email}`);
-  console.log(`  Username: ${rows[0].username || "(none)"}`);
   console.log(`  Role:     ${rows[0].role}\n`);
 } catch (err) {
   console.error(`Failed to create admin: ${err.message}`);

package/src/config/index.ts

@@ -65,6 +65,15 @@ export const baseConfigSchema = z.object({
    * instead, which costs far more than the key ever protected.
    */
   UNSUBSCRIBE_SECRET: z.string().min(16).optional(),
+  /**
+   * When true, trusts X-Forwarded-For headers from reverse proxies for client IP resolution.
+   * Defaults to false to prevent client-spoofed headers from bypassing rate limits.
+   */
+  TRUST_PROXY: z.coerce.boolean().default(false),
+  /**
+   * Comma-separated list of allowed origins for CORS on session-authenticated admin routes.
+   */
+  CORS_ORIGIN: z.string().optional(),
 });
 
 export type BaseConfig = z.infer<typeof baseConfigSchema>;

package/src/server.ts

@@ -10,6 +10,11 @@ export interface NotifkitOptions {
   port?: number;
   logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent";
   nodeEnv?: "development" | "test" | "production";
+  adminUser?: {
+    email: string;
+    password: string;
+    username?: string;
+  };
   services: (
     "api" | "delivery" | "engine" | "enricher" | "scheduler" | "ai" | "workflow" | "events" | "all"
   )[];
@@ -69,6 +74,11 @@ export class NotifkitServer extends EventEmitter {
     if (this.options.port) process.env.PORT = String(this.options.port);
     if (this.options.logLevel) process.env.LOG_LEVEL = this.options.logLevel;
     if (this.options.nodeEnv) process.env.NODE_ENV = this.options.nodeEnv;
+    if (this.options.adminUser?.email) process.env.ADMIN_EMAIL = this.options.adminUser.email;
+    if (this.options.adminUser?.password)
+      process.env.ADMIN_PASSWORD = this.options.adminUser.password;
+    if (this.options.adminUser?.username)
+      process.env.ADMIN_USERNAME = this.options.adminUser.username;
     if (this.options.workerConcurrency)
       process.env.WORKER_CONCURRENCY = String(this.options.workerConcurrency);
     if (this.options.redisOptions?.maxQueueLength)

package/src/services/api/admin-static.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { resolve, extname, join } from "node:path";
+import { resolve, extname, join, relative, isAbsolute } from "node:path";
 import { existsSync, statSync, createReadStream } from "node:fs";
 import { request as httpRequest } from "node:http";
 
@@ -155,7 +155,8 @@ export async function handleAdminRequest(
   let filePath = resolve(dashboardDir, subPath);
 
   // Security check: ensure filePath is inside dashboardDir
-  if (!filePath.startsWith(dashboardDir)) {
+  const rel = relative(dashboardDir, filePath);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
     res.writeHead(403, { "Content-Type": "text/plain" });
     res.end("Forbidden");
     return true;

package/src/services/api/handlers.ts

@@ -17,6 +17,7 @@ import {
   createAdminSession,
   revokeAdminSession,
   getAdminSession,
+  DUMMY_PASSWORD_HASH,
 } from "@/services/auth/index.js";
 import type { Preferences } from "@/contracts/index.js";
 import {
@@ -41,7 +42,7 @@ import { readJsonBody, sendJson, sendNoContent, sendValidationError } from "./ht
 import type { RouteContext } from "./router.js";
 import { globalEmitter, getPriorityBucket, normaliseTarget } from "@/shared/index.js";
 import { metrics } from "@/metrics/index.js";
-import { eq, desc, and, lt, lte, gte, sql, like, or, isNotNull } from "drizzle-orm";
+import { eq, desc, and, lt, lte, gte, sql, like, or, isNotNull, inArray } from "drizzle-orm";
 import {
   messageLogs,
   workflowDefinitions,
@@ -49,6 +50,7 @@ import {
   suppressions,
   users as dbUsers,
   userTopicPreferences,
+  deliveryOutbox,
 } from "@/db/schema.js";
 import { readBaseConfig } from "@/config/index.js";
 import { verifyUnsubscribeToken } from "@/unsubscribe/index.js";
@@ -1106,12 +1108,14 @@ export function createHandlers(deps: Deps) {
     };
 
     const streamDepths: Record<string, number> = {};
-    for (const [key, realRedisKey] of Object.entries(streamMap)) {
-      try {
-        const len = await deps.redis.native.xlen(realRedisKey);
-        streamDepths[key] = len;
-      } catch {
-        streamDepths[key] = 0;
+    if (ctx.isAdmin !== false) {
+      for (const [key, realRedisKey] of Object.entries(streamMap)) {
+        try {
+          const len = await deps.redis.native.xlen(realRedisKey);
+          streamDepths[key] = len;
+        } catch {
+          streamDepths[key] = 0;
+        }
       }
     }
 
@@ -1144,7 +1148,9 @@ export function createHandlers(deps: Deps) {
       delivered = Number(deliveredTasksRes[0]?.count ?? 0);
     }
 
-    const failed = streamDepths.DEAD_LETTER || 0;
+    // Project-scoped calls compute failure against their own task count;
+    // cluster-wide administrative calls read the global dead letter queue length.
+    const failed = ctx.projectId ? Math.max(0, total - delivered) : streamDepths.DEAD_LETTER || 0;
     const successRate = total > 0 ? Number(((delivered / total) * 100).toFixed(2)) : 100;
 
     sendJson(res, 200, {
@@ -1162,7 +1168,7 @@ export function createHandlers(deps: Deps) {
   async function getDLQMessages(
     _req: IncomingMessage,
     res: ServerResponse,
-    _ctx: RouteContext,
+    ctx: RouteContext,
   ): Promise<void> {
     try {
       const rawEntries = await deps.redis.native.xrevrange(
@@ -1170,22 +1176,38 @@ export function createHandlers(deps: Deps) {
         "+",
         "-",
         "COUNT",
-        "50",
+        "100",
       );
-      const messages = (rawEntries || []).map(([id, fields]: [string, string[]]) => {
+      const allMessages = (rawEntries || []).map(([id, fields]: [string, string[]]) => {
         const fieldMap: Record<string, string> = {};
         for (let i = 0; i < fields.length; i += 2) {
           fieldMap[fields[i]!] = fields[i + 1]!;
         }
+        let payload: any = fieldMap;
+        if (fieldMap.payload) {
+          try {
+            payload = JSON.parse(fieldMap.payload);
+          } catch {
+            payload = fieldMap.payload;
+          }
+        }
         return {
           id,
           eventType: fieldMap.eventType || fieldMap.event_type || "unknown",
-          payload: fieldMap.payload ? JSON.parse(fieldMap.payload) : fieldMap,
+          payload,
           error: fieldMap.error || fieldMap.reason || "Dead letter payload",
           timestamp: fieldMap.timestamp || new Date().toISOString(),
         };
       });
-      sendJson(res, 200, { messages });
+
+      const messages = ctx.projectId
+        ? allMessages.filter((m) => {
+            const pId = m.payload?.projectId ?? m.payload?.project_id ?? (m as any).projectId;
+            return pId === ctx.projectId;
+          })
+        : allMessages;
+
+      sendJson(res, 200, { messages: messages.slice(0, 50) });
     } catch {
       sendJson(res, 200, { messages: [] });
     }
@@ -1195,7 +1217,7 @@ export function createHandlers(deps: Deps) {
   async function replayDLQMessage(
     req: IncomingMessage,
     res: ServerResponse,
-    _ctx: RouteContext,
+    ctx: RouteContext,
   ): Promise<void> {
     const body = (await readJsonBody(req).catch(() => ({}))) as any;
     const messageId = body?.id;
@@ -1218,6 +1240,21 @@ export function createHandlers(deps: Deps) {
         fieldMap[fields[i]!] = fields[i + 1]!;
       }
 
+      let payload: any = null;
+      if (fieldMap.payload) {
+        try {
+          payload = JSON.parse(fieldMap.payload);
+        } catch {}
+      }
+
+      if (ctx.projectId) {
+        const pId = payload?.projectId ?? payload?.project_id ?? (fieldMap as any).projectId;
+        if (pId !== ctx.projectId) {
+          sendJson(res, 404, { error: "dlq_message_not_found" });
+          return;
+        }
+      }
+
       const priority = fieldMap.priority || "normal";
       const p = getPriorityBucket(priority);
       const targetStream =
@@ -1246,6 +1283,34 @@ export function createHandlers(deps: Deps) {
     if (!messageId) return sendJson(res, 400, { error: "missing_id" });
 
     try {
+      if (ctx.projectId) {
+        const rawEntries = await deps.redis.native.xrange(
+          STREAMS.DEAD_LETTER,
+          messageId,
+          messageId,
+        );
+        if (!rawEntries || rawEntries.length === 0 || !rawEntries[0]) {
+          sendJson(res, 404, { error: "dlq_message_not_found" });
+          return;
+        }
+        const fields = rawEntries[0][1];
+        const fieldMap: Record<string, string> = {};
+        for (let i = 0; i < fields.length; i += 2) {
+          fieldMap[fields[i]!] = fields[i + 1]!;
+        }
+        let payload: any = null;
+        if (fieldMap.payload) {
+          try {
+            payload = JSON.parse(fieldMap.payload);
+          } catch {}
+        }
+        const pId = payload?.projectId ?? payload?.project_id ?? (fieldMap as any).projectId;
+        if (pId !== ctx.projectId) {
+          sendJson(res, 404, { error: "dlq_message_not_found" });
+          return;
+        }
+      }
+
       await deps.redis.native.xdel(STREAMS.DEAD_LETTER, messageId);
       sendJson(res, 200, { success: true });
     } catch (err: any) {
@@ -1298,12 +1363,25 @@ export function createHandlers(deps: Deps) {
     if (!user) return sendJson(res, 404, { error: "user_not_found", id: userId });
 
     const contacts = await deps.contactRepo.findByUserId(ctx.projectId!, userId);
-    const logs = await deps.db
-      .select()
-      .from(messageLogs)
-      .where(eq(messageLogs.projectId, ctx.projectId!))
-      .orderBy(desc(messageLogs.timestamp))
-      .limit(50);
+    const contactTargets = contacts.map((c) => c.target);
+    let logs: any[] = [];
+    if (contactTargets.length > 0) {
+      const outboxRows = await deps.db
+        .select({ taskId: deliveryOutbox.taskId })
+        .from(deliveryOutbox)
+        .where(inArray(deliveryOutbox.destination, contactTargets));
+      const taskIds = Array.from(new Set(outboxRows.map((r: any) => r.taskId)));
+      if (taskIds.length > 0) {
+        logs = await deps.db
+          .select()
+          .from(messageLogs)
+          .where(
+            and(eq(messageLogs.projectId, ctx.projectId!), inArray(messageLogs.taskId, taskIds)),
+          )
+          .orderBy(desc(messageLogs.timestamp))
+          .limit(50);
+      }
+    }
 
     sendJson(res, 200, { ...user, contacts, logs });
   }
@@ -1764,7 +1842,7 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
         and(
           eq(suppressions.projectId, ctx.projectId!),
           eq(suppressions.channel, channel as any),
-          eq(suppressions.target, normaliseTarget(decodeURIComponent(target))),
+          eq(suppressions.target, normaliseTarget(target)),
         ),
       );
 
@@ -1796,13 +1874,9 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
 
     const { identifier, password } = parsed.data;
     const user = await deps.adminUserRepo.findByEmailOrUsername(identifier);
-    if (!user) {
-      sendJson(res, 401, { error: "unauthorized", message: "Invalid credentials" });
-      return;
-    }
-
-    const isValid = await verifyPassword(password, user.passwordHash);
-    if (!isValid) {
+    const targetHash = user ? user.passwordHash : DUMMY_PASSWORD_HASH;
+    const isValid = await verifyPassword(password, targetHash);
+    if (!user || !isValid) {
       sendJson(res, 401, { error: "unauthorized", message: "Invalid credentials" });
       return;
     }

package/src/services/api/main.ts

@@ -61,6 +61,20 @@ export function extractAuthToken(req: Pick<IncomingMessage, "headers">): string
   return undefined;
 }
 
+/**
+ * Resolves client IP address, respecting reverse proxy headers only when TRUST_PROXY is enabled.
+ */
+export function getClientIp(req: IncomingMessage, trustProxy: boolean): string {
+  if (trustProxy) {
+    const forwarded = req.headers["x-forwarded-for"];
+    if (typeof forwarded === "string") {
+      const first = forwarded.split(",")[0]?.trim();
+      if (first) return first;
+    }
+  }
+  return req.socket.remoteAddress || "unknown";
+}
+
 async function handleCreateProject(req: IncomingMessage, res: ServerResponse): Promise<void> {
   const parsed = z.object({ name: z.string().min(1) }).safeParse(await readJsonBody(req));
   if (!parsed.success) {
@@ -130,7 +144,42 @@ async function handleHealth(_req: IncomingMessage, res: ServerResponse): Promise
   sendJson(res, statusCode, response);
 }
 
-async function handleMetrics(_req: IncomingMessage, res: ServerResponse): Promise<void> {
+async function handleMetrics(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const remoteIp = req.socket.remoteAddress ?? "";
+  const isLoopback =
+    remoteIp === "127.0.0.1" ||
+    remoteIp === "::1" ||
+    remoteIp === "::ffff:127.0.0.1" ||
+    remoteIp === "localhost";
+
+  let authorized = isLoopback;
+  if (!authorized) {
+    const token = extractAuthToken(req);
+    if (token) {
+      if (token.startsWith("nk_sess_") && redis?.native) {
+        const session = await getAdminSession(redis.native, token);
+        if (session) authorized = true;
+      } else if (config.ADMIN_API_KEY) {
+        const expectedBuffer = Buffer.from(config.ADMIN_API_KEY);
+        const providedBuffer = Buffer.from(token);
+        if (
+          expectedBuffer.length === providedBuffer.length &&
+          timingSafeEqual(expectedBuffer, providedBuffer)
+        ) {
+          authorized = true;
+        }
+      }
+    }
+  }
+
+  if (!authorized) {
+    sendJson(res, 401, {
+      error: "unauthorized",
+      message: "Metrics endpoint requires admin credentials",
+    });
+    return;
+  }
+
   const registry = getMetricsRegistry();
   res.writeHead(200, { "Content-Type": registry.contentType });
   res.end(await registry.metrics());
@@ -167,6 +216,15 @@ let server: ReturnType<typeof createServer>;
 
 export async function startApiServer() {
   logger = createLogger({ name: "api", level: config.LOG_LEVEL });
+
+  if (config.NODE_ENV === "production" && !config.UNSUBSCRIBE_SECRET) {
+    logger.fatal(
+      "UNSUBSCRIBE_SECRET is required in production. Without it, all unsubscribe links " +
+        "return 400 and opt-outs are silently dropped. Set a random string of 32+ characters and restart.",
+    );
+    process.exit(1);
+  }
+
   redis = new RedisClient({ url: config.REDIS_URL, name: "api", logger });
   const dbData = createDatabase({ url: config.DATABASE_URL, applicationName: "api", logger });
   sql = dbData.sql;
@@ -280,8 +338,28 @@ export async function startApiServer() {
   server.keepAliveTimeout = 5_000;
 
   async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
-    // Add CORS headers for browser clients (like the Next.js dashboard)
-    res.setHeader("Access-Control-Allow-Origin", "*");
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const origin = req.headers["origin"] as string | undefined;
+    const allowedOrigins = (config.CORS_ORIGIN ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const isSessionRoute =
+      url.pathname.startsWith("/v1/auth/") ||
+      url.pathname === "/v1/projects" ||
+      url.pathname.startsWith("/v1/projects/") ||
+      url.pathname.startsWith("/v1/system/") ||
+      url.pathname.startsWith("/v1/dlq");
+
+    if (isSessionRoute) {
+      if (origin && allowedOrigins.includes(origin)) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+      }
+    } else {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+    }
+
     res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
     res.setHeader(
       "Access-Control-Allow-Headers",
@@ -294,8 +372,6 @@ export async function startApiServer() {
       return;
     }
 
-    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
-
     if (url.pathname === "/admin" || url.pathname.startsWith("/admin/")) {
       const handled = await handleAdminRequest(req, res, url);
       if (handled) return;
@@ -304,6 +380,7 @@ export async function startApiServer() {
     let projectId: string | undefined = undefined;
     let projectRateLimitRpm = 600;
     let keyRole: "admin" | "read_only" = "admin";
+    let isAdminToken = false;
 
     const isProjectManagement =
       url.pathname === "/v1/projects" || url.pathname.startsWith("/v1/projects/");
@@ -330,7 +407,6 @@ export async function startApiServer() {
         return;
       }
 
-      let isAdminToken = false;
       if (token.startsWith("nk_sess_")) {
         const session = await getAdminSession(redis.native, token);
         if (session) {
@@ -472,6 +548,7 @@ export async function startApiServer() {
         sendJson(res, 401, { error: "unauthorized", message: "Invalid admin token" });
         return;
       }
+      isAdminToken = true;
     }
 
     // The unsubscribe routes skip the block above, and with it the per-project
@@ -479,10 +556,7 @@ export async function startApiServer() {
     // an open endpoint cannot be used to hammer the process. Generous, because
     // a shared corporate egress IP can legitimately produce a burst.
     if (isPublicUnsubscribe) {
-      const clientIp =
-        (req.headers["x-forwarded-for"] as string | undefined)?.split(",")[0]?.trim() ||
-        req.socket.remoteAddress ||
-        "unknown";
+      const clientIp = getClientIp(req, Boolean(config.TRUST_PROXY));
       try {
         const key = `rate-limit:api:unsub:${clientIp}`;
         const count = await redis.native.incr(key);
@@ -499,6 +573,27 @@ export async function startApiServer() {
       }
     }
 
+    // The login route is unauthenticated and CPU-intensive due to password hashing (scrypt).
+    // Throttle login attempts per IP to prevent credential brute-forcing and CPU exhaustion.
+    if (isPublicAuth) {
+      const clientIp = getClientIp(req, Boolean(config.TRUST_PROXY));
+      try {
+        const key = `rate-limit:api:auth:${clientIp}`;
+        const count = await redis.native.incr(key);
+        if (count === 1) await redis.native.expire(key, 60);
+        if (count > 10) {
+          res.setHeader("Retry-After", "60");
+          sendJson(res, 429, {
+            error: "too_many_requests",
+            message: "Too many login attempts. Please try again later.",
+          });
+          return;
+        }
+      } catch (err) {
+        logger.warn({ err }, "auth rate limit unavailable — allowing request");
+      }
+    }
+
     const route = router.match(req.method ?? "GET", url.pathname);
 
     if (!route) {
@@ -506,7 +601,13 @@ export async function startApiServer() {
       return;
     }
 
-    const ctx = { params: route.params, query: url.searchParams, projectId, role: keyRole };
+    const ctx = {
+      params: route.params,
+      query: url.searchParams,
+      projectId,
+      role: keyRole,
+      isAdmin: isAdminToken,
+    };
 
     void Promise.resolve(route.handler(req, res, ctx)).catch((err: unknown) => {
       if (err instanceof HttpError) {

package/src/services/api/router.ts

@@ -5,6 +5,7 @@ export interface RouteContext {
   query: URLSearchParams;
   projectId?: string;
   role?: "admin" | "read_only";
+  isAdmin?: boolean;
 }
 
 export type RouteHandler = (
@@ -65,7 +66,12 @@ export class Router {
         const seg = route.segments[i]!;
         const part = parts[i]!;
         if (seg.startsWith(":")) {
-          params[seg.slice(1)] = decodeURIComponent(part);
+          try {
+            params[seg.slice(1)] = decodeURIComponent(part);
+          } catch {
+            ok = false;
+            break;
+          }
         } else if (seg !== part) {
           ok = false;
           break;

package/src/services/auth/index.ts

@@ -8,6 +8,14 @@ const scryptAsync = promisify(scrypt);
 const DEFAULT_SESSION_TTL_SECONDS = 7 * 24 * 60 * 60; // 7 days
 const SESSION_PREFIX = "notif:session:";
 
+/**
+ * Pre-computed dummy hash conforming to salt(16 bytes hex):hash(64 bytes hex).
+ * Used during authentication failure to equalize execution time and prevent
+ * user enumeration via scrypt timing side-channels.
+ */
+export const DUMMY_PASSWORD_HASH =
+  "00000000000000000000000000000000:00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000";
+
 export interface AdminSession {
   token: string;
   adminId: string;