easy-ping 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,367 +1,60 @@
-import { verifyToken } from './chunk-W3BMEPPQ.js';
-export { DEFAULT_TOKEN_TTL_SECONDS, expiresIn, signToken, verifyToken } from './chunk-W3BMEPPQ.js';
-export { defineClientPlugin, definePlugin } from './chunk-BV3U542P.js';
-import { consoleLogger, createPluginStore, ConfigError, ValidationError } from './chunk-OZSOIX23.js';
-export { ConfigError, EasyPingError, ValidationError, consoleLogger } from './chunk-OZSOIX23.js';
+export { defineClientPlugin, definePlugin } from './chunk-E4IZ2CQC.js';
+import { createRunner } from './chunk-GJNLOQJS.js';
+export { createRunner, redactErrorMessage } from './chunk-GJNLOQJS.js';
+import { createHandler, createScopedSigner } from './chunk-BECMTNK7.js';
+export { DEFAULT_TOKEN_TTL_SECONDS, MAX_BODY_BYTES, MAX_TOKEN_TTL_SECONDS, expiresIn, readJsonBody, signToken, verifyToken } from './chunk-BECMTNK7.js';
+import { consoleLogger, ConfigError, createPluginStore, ValidationError } from './chunk-3VOQOGDR.js';
+export { ConfigError, EasyPingError, ValidationError, consoleLogger } from './chunk-3VOQOGDR.js';
+import './chunk-AEYYTE5I.js';
 export { decodeBase64Url, encodeBase64Url } from './chunk-PTGHMCCG.js';
-import './chunk-NYDVNMKG.js';
 
 // src/core/definition.ts
 function defineNotification(definition) {
   return definition;
 }
 
-// src/core/handler.ts
-var json = (body, status = 200) => new Response(JSON.stringify(body), {
-  status,
-  headers: { "content-type": "application/json" }
-});
-var empty = (status) => new Response(null, { status });
-var MAX_READ_IDS = 200;
-function timingSafeEqual(a, b) {
-  const encoder = new TextEncoder();
-  const left = encoder.encode(a);
-  const right = encoder.encode(b);
-  let diff = left.length ^ right.length;
-  const length = Math.max(left.length, right.length);
-  for (let i = 0; i < length; i += 1) {
-    diff |= (left[i] ?? 0) ^ (right[i] ?? 0);
-  }
-  return diff === 0;
-}
-function routePath(url, basePath) {
-  const index = url.pathname.indexOf(basePath);
-  if (index < 0) return url.pathname;
-  return url.pathname.slice(index + basePath.length) || "/";
-}
-async function readJson(request) {
-  try {
-    const body = await request.json();
-    return body && typeof body === "object" ? body : {};
-  } catch {
-    return {};
-  }
-}
-function createHandler(deps) {
-  async function resolveUserId(request) {
-    try {
-      return await deps.session.getUserId(request);
-    } catch (error) {
-      deps.logger.error("session.getUserId threw", { error });
-      return "error";
-    }
-  }
-  async function handleCron(request) {
-    if (!deps.cronSecret) return empty(404);
-    const header = request.headers.get("authorization") ?? "";
-    const presented = header.startsWith("Bearer ") ? header.slice(7) : header;
-    if (!timingSafeEqual(presented, deps.cronSecret)) return empty(401);
-    const result = await deps.runner.drain();
-    return json(result);
-  }
-  async function handlePluginRoute(route, request, url) {
-    if (route.scope.type === "user") {
-      const userId = await resolveUserId(request);
-      if (userId === "error") return empty(500);
-      if (userId === null) return empty(401);
-      return route.handler({ request, userId, claims: null, params: {} });
-    }
-    if (route.scope.type === "machine") {
-      if (!deps.cronSecret) return empty(404);
-      const header = request.headers.get("authorization") ?? "";
-      const presented = header.startsWith("Bearer ") ? header.slice(7) : header;
-      if (!timingSafeEqual(presented, deps.cronSecret)) return empty(401);
-      return route.handler({ request, userId: null, claims: null, params: {} });
-    }
-    if (route.scope.type === "signed") {
-      const token = url.searchParams.get("token") ?? (request.headers.get("authorization") ?? "").replace(/^Bearer /, "");
-      const claims = await verifyToken(deps.secret, token, route.scope.purpose);
-      if (!claims) return empty(400);
-      return route.handler({ request, userId: claims.uid, claims, params: {} });
-    }
-    return route.handler({ request, userId: null, claims: null, params: {} });
-  }
-  async function handle(request) {
-    const url = new URL(request.url);
-    const path = routePath(url, deps.basePath);
-    if (path === "/cron") {
-      if (request.method !== "POST") return empty(405);
-      return handleCron(request);
-    }
-    const pluginRoute = deps.pluginRoutes?.find(
-      (route) => route.path === path && route.method === request.method
-    );
-    if (pluginRoute) return handlePluginRoute(pluginRoute, request, url);
-    const userId = await resolveUserId(request);
-    if (userId === "error") return empty(500);
-    if (userId === null) return empty(401);
-    if (request.method === "GET" && path === "/") {
-      const limitParam = Number(url.searchParams.get("limit") ?? 20);
-      const limit = Number.isFinite(limitParam) ? Math.min(Math.max(limitParam, 1), 100) : 20;
-      const cursor = url.searchParams.get("cursor");
-      const [page, unseenCount] = await Promise.all([
-        deps.adapter.listNotifications({
-          userId,
-          limit,
-          ...cursor ? { cursor } : {},
-          ...url.searchParams.get("unreadOnly") === "true" ? { unreadOnly: true } : {}
-        }),
-        cursor ? Promise.resolve(null) : deps.adapter.countUnseen(userId)
-      ]);
-      return json(unseenCount === null ? page : { ...page, unseenCount });
-    }
-    if (request.method === "GET" && path === "/count") {
-      return json({ unseen: await deps.adapter.countUnseen(userId) });
-    }
-    if (request.method === "POST" && path === "/seen") {
-      const body = await readJson(request);
-      const before = typeof body.before === "string" ? new Date(body.before) : null;
-      const cutoff = before && !Number.isNaN(before.getTime()) ? new Date(before.getTime() + 1) : /* @__PURE__ */ new Date();
-      await deps.adapter.markSeen(userId, cutoff);
-      return json({ ok: true });
-    }
-    if (request.method === "POST" && path === "/read") {
-      const body = await readJson(request);
-      const ids = Array.isArray(body.ids) ? body.ids.filter((id) => typeof id === "string") : [];
-      if (ids.length === 0) return json({ error: "ids must be a non-empty string array" }, 400);
-      if (ids.length > MAX_READ_IDS) {
-        return json({ error: `at most ${MAX_READ_IDS} ids per request` }, 400);
-      }
-      const updated = await deps.adapter.markRead(userId, ids);
-      return updated === 0 ? empty(404) : json({ updated });
-    }
-    if (request.method === "POST" && path === "/read-all") {
-      return json({ updated: await deps.adapter.markAllRead(userId) });
-    }
-    return empty(404);
-  }
-  return {
-    handle,
-    GET: handle,
-    POST: handle
-  };
-}
-
-// src/core/backoff.ts
-var SCHEDULE_MS = [3e4, 12e4, 48e4, 192e4];
-function backoffMs(attempt, strategy = "exponential") {
-  if (typeof strategy === "function") return Math.max(0, strategy(attempt));
-  const index = Math.min(Math.max(attempt, 1), SCHEDULE_MS.length) - 1;
-  const base = SCHEDULE_MS[index] ?? SCHEDULE_MS[SCHEDULE_MS.length - 1] ?? 3e4;
-  return Math.round(base * (0.8 + Math.random() * 0.4));
-}
-var nextAttemptAt = (attempt, strategy, now = /* @__PURE__ */ new Date()) => new Date(now.getTime() + backoffMs(attempt, strategy));
+// src/core/html.ts
+var ESCAPES = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+var escapeHtml = (value) => String(value ?? "").replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
 
-// src/core/runner.ts
-var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-async function withTimeout(run, ms, label) {
-  const controller = new AbortController();
-  let timer;
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => {
-      controller.abort();
-      reject(new Error(`${label} timed out after ${ms}ms`));
-    }, ms);
-  });
-  try {
-    return await Promise.race([run(controller.signal), timeout]);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-var message = (error) => error instanceof Error ? error.message : String(error);
-function createRunner(deps) {
-  async function deliverOne(delivery, recipient) {
-    if (!recipient) {
-      return { result: "failed", error: "recipient could not be resolved", retryable: false };
-    }
-    if (delivery.channel === "inApp") {
-      return { result: "sent" };
-    }
-    if (delivery.channel === "email") {
-      const provider = deps.channels.email?.provider;
-      if (!provider) {
-        return { result: "failed", error: "no email provider configured", retryable: false };
-      }
-      const to = recipient.email;
-      if (!to) {
-        return { result: "failed", error: "recipient has no email address", retryable: false };
-      }
-      const email = deps.definitions[delivery.notification.type]?.email;
-      if (!email) {
-        return {
-          result: "failed",
-          error: `notification type "${delivery.notification.type}" has no email template`,
-          retryable: false
-        };
-      }
-      try {
-        const payload = delivery.notification.payload;
-        const html = await email.template(payload);
-        await withTimeout(
-          (signal) => provider.send({
-            to,
-            subject: email.subject(payload),
-            html,
-            // Delivery is at-least-once; the provider dedupes on this.
-            idempotencyKey: delivery.id,
-            signal
-          }),
-          provider.timeoutMs ?? 3e4,
-          `${provider.name} send`
-        );
-        return { result: "sent" };
-      } catch (error) {
-        return {
-          result: "failed",
-          error: message(error),
-          retryable: provider.isRetryable(error)
-        };
-      }
-    }
-    const owner = deps.plugins.find(
-      (plugin) => plugin.channels?.includes(delivery.channel) && plugin.hooks?.deliver
-    );
-    if (!owner?.hooks?.deliver) {
-      return {
-        result: "failed",
-        error: `no plugin delivers channel "${delivery.channel}"`,
-        retryable: false
-      };
-    }
-    try {
-      return await withTimeout(
-        (signal) => Promise.resolve(
-          // biome-ignore lint/style/noNonNullAssertion: guarded directly above
-          owner.hooks.deliver({
-            channel: delivery.channel,
-            deliveryId: delivery.id,
-            attempt: delivery.attempts + 1,
-            recipient,
-            notification: {
-              id: delivery.notificationId,
-              userId: delivery.notification.userId,
-              type: delivery.notification.type,
-              payload: delivery.notification.payload
-            },
-            signal
-          })
-        ),
-        3e4,
-        `plugin "${owner.id}" deliver`
-      );
-    } catch (error) {
-      return { result: "failed", error: message(error), retryable: true };
-    }
-  }
-  async function notifyAfterDeliver(delivery, outcome) {
-    const isTerminal = outcome.result !== "failed" || !outcome.retryable || delivery.attempts + 1 >= delivery.maxAttempts;
-    for (const plugin of deps.plugins) {
-      const hook = plugin.hooks?.afterDeliver;
-      if (!hook) continue;
-      try {
-        await hook({
-          deliveryId: delivery.id,
-          notificationId: delivery.notificationId,
-          userId: delivery.notification.userId,
-          channel: delivery.channel,
-          outcome,
-          attempt: delivery.attempts + 1,
-          isTerminal
-        });
-      } catch (error) {
-        deps.logger.error(`plugin "${plugin.id}" afterDeliver threw; ignoring`, {
-          deliveryId: delivery.id,
-          error
-        });
+// src/core/rate-limit.ts
+var clientAddress = (request) => {
+  const headers = request.headers;
+  return headers.get("cf-connecting-ip") ?? headers.get("x-real-ip") ?? headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? null;
+};
+function createRateLimiter(config) {
+  const keyOf = config.key ?? clientAddress;
+  const buckets = /* @__PURE__ */ new Map();
+  let lastSweep = 0;
+  return (request) => {
+    const key = keyOf(request);
+    if (key === null) return null;
+    const now = Date.now();
+    if (now - lastSweep > config.windowMs) {
+      for (const [id, bucket2] of buckets) if (bucket2.resetAt <= now) buckets.delete(id);
+      lastSweep = now;
+    }
+    let bucket = buckets.get(key);
+    if (!bucket || bucket.resetAt <= now) {
+      bucket = { count: 0, resetAt: now + config.windowMs };
+      buckets.set(key, bucket);
+    }
+    bucket.count += 1;
+    if (bucket.count <= config.max) return null;
+    return new Response(null, {
+      status: 429,
+      headers: {
+        "retry-after": String(Math.max(1, Math.ceil((bucket.resetAt - now) / 1e3))),
+        "cache-control": "private, no-store"
       }
-    }
-  }
-  async function runOnce(options = {}) {
-    const claimToken = crypto.randomUUID();
-    const claimed = await deps.adapter.claimPendingDeliveries({
-      limit: options.limit ?? deps.batchSize,
-      leaseMs: deps.leaseMs,
-      claimToken,
-      ...options.channels ? { channels: options.channels } : {},
-      ...options.ids ? { ids: options.ids } : {}
     });
-    if (claimed.length === 0) return { claimed: 0, sent: 0, failed: 0, skipped: 0 };
-    const userIds = [...new Set(claimed.map((row) => row.notification.userId))];
-    const recipients = await deps.getRecipients(userIds);
-    const byUserId = new Map(recipients.map((recipient) => [recipient.userId, recipient]));
-    const releases = [];
-    let sent = 0;
-    let failed = 0;
-    let skipped = 0;
-    for (const delivery of claimed) {
-      const outcome = await deliverOne(delivery, byUserId.get(delivery.notification.userId));
-      if (outcome.result === "sent") sent += 1;
-      else if (outcome.result === "skipped") skipped += 1;
-      else failed += 1;
-      releases.push({
-        id: delivery.id,
-        claimToken,
-        outcome,
-        ...outcome.result === "failed" && outcome.retryable ? { nextAttemptAt: nextAttemptAt(delivery.attempts + 1, deps.backoff) } : {}
-      });
-      await notifyAfterDeliver(delivery, outcome);
-    }
-    await deps.adapter.releaseDeliveries(releases);
-    return { claimed: claimed.length, sent, failed, skipped };
-  }
-  async function drain(options = {}) {
-    const maxSweeps = options.maxSweeps ?? 50;
-    const total = { claimed: 0, sent: 0, failed: 0, skipped: 0 };
-    for (let sweep = 0; sweep < maxSweeps; sweep += 1) {
-      const result = await runOnce(options.ids ? { ids: options.ids } : {});
-      total.claimed += result.claimed;
-      total.sent += result.sent;
-      total.failed += result.failed;
-      total.skipped += result.skipped;
-      if (result.claimed === 0) break;
-    }
-    return total;
-  }
-  let warnedMissingWaitUntil = false;
-  function scheduleDeferred(waitUntil, ids) {
-    if (waitUntil) {
-      waitUntil(
-        drain({ maxSweeps: 10, ...ids ? { ids } : {} }).catch(
-          (error) => deps.logger.error("deferred sweep failed", { error })
-        )
-      );
-      return;
-    }
-    if (!warnedMissingWaitUntil) {
-      warnedMissingWaitUntil = true;
-      deps.logger.warn(
-        "delivery.mode is 'deferred' but no delivery.waitUntil was supplied \u2014 falling back to the cron sweep. Notifications are not lost, but they will not be delivered until POST /cron runs."
-      );
-    }
-  }
-  function startWorker(options = {}) {
-    const intervalMs = options.intervalMs ?? 1e3;
-    let stopped = false;
-    const loop = (async () => {
-      while (!stopped) {
-        try {
-          const result = await runOnce({ limit: options.batchSize ?? deps.batchSize });
-          if (result.claimed === 0) await sleep(intervalMs);
-        } catch (error) {
-          deps.logger.error("worker sweep failed", { error });
-          await sleep(intervalMs);
-        }
-      }
-    })();
-    return {
-      stop: async () => {
-        stopped = true;
-        await loop;
-      }
-    };
-  }
-  return { runOnce, drain, scheduleDeferred, startWorker };
+  };
 }
 
 // src/core/send.ts
@@ -504,8 +197,7 @@ async function runSend(type, input, deps) {
       id: newId(),
       channel: decision.channel,
       maxAttempts: definition.maxAttempts ?? deps.maxAttempts,
-      // `defer` needs no machinery beyond not_before — the claim query
-      // already refuses rows whose time has not come. RFC 0004 §4.2.
+      // defer is just not_before; the claim query refuses rows whose time has not come. RFC 0004 §4.2.
       notBefore: decision.action === "defer" && decision.notBefore ? decision.notBefore : now
     }));
     if (deliveries.length === 0) {
@@ -555,6 +247,14 @@ async function runSend(type, input, deps) {
 }
 
 // src/core/instance.ts
+var CORE_ROUTES = [
+  { method: "GET", path: "/", scope: { type: "user" }, owner: "core" },
+  { method: "GET", path: "/count", scope: { type: "user" }, owner: "core" },
+  { method: "POST", path: "/seen", scope: { type: "user" }, owner: "core" },
+  { method: "POST", path: "/read", scope: { type: "user" }, owner: "core" },
+  { method: "POST", path: "/read-all", scope: { type: "user" }, owner: "core" },
+  { method: "POST", path: "/cron", scope: { type: "machine" }, owner: "core" }
+];
 var DEFAULTS = {
   maxAttempts: 5,
   leaseMs: 6e4,
@@ -562,6 +262,24 @@ var DEFAULTS = {
   basePath: "/api/notifications",
   mode: "cron"
 };
+var MIN_SECRET_LENGTH = 16;
+var PLACEHOLDER_SECRETS = /* @__PURE__ */ new Set([
+  "secret",
+  "changeme",
+  "change-me",
+  "replace-me",
+  "replace-me-too",
+  "password",
+  "demo-signing-secret",
+  "demo-cron-secret"
+]);
+function checkSecretStrength(name, value) {
+  if (value.length < MIN_SECRET_LENGTH || PLACEHOLDER_SECRETS.has(value.toLowerCase())) {
+    throw new ConfigError(
+      `\`${name}\` must be at least ${MIN_SECRET_LENGTH} characters and not a placeholder. Generate one with \`openssl rand -base64 32\`.`
+    );
+  }
+}
 function validate(config, plugins) {
   if (!config.database) throw new ConfigError("`database` is required.");
   if (!config.notifications) throw new ConfigError("`notifications` is required.");
@@ -575,6 +293,12 @@ function validate(config, plugins) {
       "`secret` is required \u2014 it signs unsubscribe and other session-less links. Adding it later is a breaking change, so it is mandatory from the start."
     );
   }
+  checkSecretStrength("secret", config.secret);
+  if (config.cron?.secret) checkSecretStrength("cron.secret", config.cron.secret);
+  if (config.machineSecret) checkSecretStrength("machineSecret", config.machineSecret);
+  if (config.rateLimit && (config.rateLimit.max < 1 || config.rateLimit.windowMs < 1)) {
+    throw new ConfigError("`rateLimit.max` and `rateLimit.windowMs` must both be positive.");
+  }
   if (typeof config.getRecipients !== "function") {
     throw new ConfigError("`getRecipients` is required to resolve emails and timezones.");
   }
@@ -643,6 +367,15 @@ function easyPing(config) {
       "delivery.mode is 'deferred' but no delivery.waitUntil was supplied; delivery will wait for the cron sweep."
     );
   }
+  for (const plugin of plugins) {
+    for (const route of plugin.routes ?? []) {
+      if (route.scope.type === "custom") {
+        warnings.push(
+          `plugin "${plugin.id}" mounts ${route.method} ${route.path} with custom auth: ` + route.scope.justification
+        );
+      }
+    }
+  }
   for (const warning of warnings) logger.warn(warning);
   const runner = createRunner({
     adapter: config.database,
@@ -664,7 +397,13 @@ function easyPing(config) {
     secret: config.secret,
     basePath: config.basePath ?? DEFAULTS.basePath,
     pluginRoutes,
-    ...config.cron?.secret ? { cronSecret: config.cron.secret } : {}
+    trustedOrigins: config.trustedOrigins,
+    onRequest: config.onRequest,
+    maxBodyBytes: config.maxBodyBytes,
+    rateLimit: config.rateLimit ? createRateLimiter(config.rateLimit) : void 0,
+    cronMaxSweeps: config.cron?.maxSweeps,
+    ...config.cron?.secret ? { cronSecret: config.cron.secret } : {},
+    ...config.machineSecret ?? config.cron?.secret ? { machineSecret: config.machineSecret ?? config.cron?.secret } : {}
   });
   async function send(type, args) {
     const result = await runSend(
@@ -696,10 +435,21 @@ function easyPing(config) {
     return result;
   }
   for (const plugin of plugins) {
+    const purposes = new Set(
+      (plugin.routes ?? []).flatMap(
+        (route) => route.scope.type === "signed" ? [route.scope.purpose] : []
+      )
+    );
     plugin.init?.({
       store: createPluginStore(plugin.id, plugin.schema, config.database, tablePrefix),
-      secret: config.secret,
+      sign: createScopedSigner(
+        config.secret,
+        plugin.id,
+        purposes,
+        (message) => new ConfigError(message)
+      ),
       logger,
+      notificationTypes: Object.keys(config.notifications),
       getRecipients: config.getRecipients,
       send: (type, args) => send(type, args)
     });
@@ -708,6 +458,17 @@ function easyPing(config) {
     send,
     handler,
     startWorker: (options) => runner.startWorker(options ?? {}),
+    listRoutes: () => [
+      ...CORE_ROUTES.filter((route) => route.path !== "/cron" || Boolean(config.cron?.secret)),
+      ...plugins.flatMap(
+        (plugin) => (plugin.routes ?? []).map((route) => ({
+          method: route.method,
+          path: route.path,
+          scope: route.scope,
+          owner: plugin.id
+        }))
+      )
+    ],
     getFailedDeliveries: (options = {}) => config.database.getFailedDeliveries({
       since: options.since ?? new Date(Date.now() - 24 * 36e5),
       limit: Math.min(options.limit ?? 100, 1e3)
@@ -724,6 +485,6 @@ function easyPing(config) {
   };
 }
 
-export { createRunner, defineNotification, easyPing };
+export { MIN_SECRET_LENGTH, createRateLimiter, defineNotification, easyPing, escapeHtml };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map