@iann29/rastro 0.1.0-alpha.3 → 0.1.0-alpha.5

package/src/component/http.ts

@@ -7,6 +7,7 @@ import {
   MAX_BATCH_BYTES,
   MAX_BATCH_EVENT_GROUPS,
   MAX_BATCH_EVENTS,
+  RATE_LIMIT_WINDOW_MS,
 } from "./constants.js";
 import {
   classifyIp,
@@ -19,6 +20,8 @@ import {
 } from "./geo.js";
 import { isPlainRecord } from "./guards.js";
 import { sanitizeEvent } from "./sanitize.js";
+import { deriveVisitorKey, randomSecret } from "./identity.js";
+import { classifyClient, isKnownBot } from "./useragent.js";
 import type { TrackerEvent } from "./validators.js";
 import {
   TRACKER_GZIP_BASE64,
@@ -35,9 +38,16 @@ http.route({
   path: "/events",
   method: "POST",
   handler: httpAction(async (ctx, request) => {
+    const requestId = crypto.randomUUID();
     const origin = request.headers.get("origin");
-    if (!origin) return json({ error: { code: "ORIGIN_REQUIRED" } }, 400);
-    const headers = corsHeaders(origin);
+    if (!origin) {
+      return json(
+        { error: { code: "ORIGIN_REQUIRED" } },
+        400,
+        requestIdHeaders(requestId),
+      );
+    }
+    const headers = corsHeaders(origin, requestId);
     const contentLength = Number(request.headers.get("content-length"));
     if (Number.isFinite(contentLength) && contentLength > MAX_BATCH_BYTES) {
       return json(
@@ -80,9 +90,34 @@ http.route({
     const edgeGeo = proxyRequestTrusted ? geoFromHeaders(request) : {};
     const userAgent =
       metadata.userAgent ?? request.headers.get("user-agent") ?? "";
+    // Self-declared bots never reach a transaction; the response keeps the
+    // counter shape the tracker expects and names the reason in a header.
+    if (isKnownBot(userAgent)) {
+      return json(
+        { accepted: 0, duplicates: 0, rejected: payload.events.length },
+        200,
+        { ...headers, "X-Rastro-Rejected": "bot" },
+      );
+    }
+    // Anonymous batches (visitorId === sessionId) get a salted daily key so
+    // repeat visits count once; the IP itself stops here.
+    const anonymous = payload.events.some(
+      (event) => event.visitorId === event.sessionId,
+    );
+    const visitorKey =
+      anonymous && clientIp.ip && userAgent
+        ? await deriveVisitorKey({
+            secret: await visitorSecret(ctx),
+            now: Date.now(),
+            siteId: payload.siteId,
+            ip: clientIp.ip,
+            userAgent,
+          })
+        : undefined;
     const context = {
       ...edgeGeo,
-      ...classifyUserAgent(userAgent),
+      ...classifyClient(userAgent, request.headers),
+      ...(visitorKey ? { visitorKey } : {}),
     };
 
     try {
@@ -100,6 +135,7 @@ http.route({
       ) {
         const events = enrichmentCandidateEvents(payload.events);
         if (events) {
+          let stage: GeoIpFailureStage = "claim";
           try {
             const claim = await ctx.runMutation(
               internal.geo.claimEnrichment,
@@ -110,22 +146,34 @@ http.route({
               },
             );
             if (claim.sessionIds.length > 0) {
+              stage = "resolve";
               const providerGeo = await resolveGeoIp(
                 clientIp.ip,
                 env.RASTRO_GEOIP_PROVIDER!,
                 env.RASTRO_GEOIP_TOKEN,
               );
               if (providerGeo) {
+                stage = "apply";
                 await ctx.runMutation(internal.geo.applyEnrichment, {
                   siteId: payload.siteId as Id<"sites">,
                   sessionIds: claim.sessionIds,
                   events: claim.events,
                   context: providerGeo,
                 });
+              } else {
+                logGeoIpFailure(
+                  requestId,
+                  stage,
+                  env.RASTRO_GEOIP_PROVIDER!,
+                );
               }
             }
           } catch {
-            // Analytics ingestion remains available if optional enrichment fails.
+            logGeoIpFailure(
+              requestId,
+              stage,
+              env.RASTRO_GEOIP_PROVIDER!,
+            );
           }
         }
       }
@@ -139,9 +187,25 @@ http.route({
             : data.code === "RATE_LIMITED"
               ? 429
               : 400;
-        return json({ error: data }, status, headers);
+        return json(
+          { error: data },
+          status,
+          status === 429
+            ? {
+                ...headers,
+                "Retry-After": String(
+                  Math.ceil(RATE_LIMIT_WINDOW_MS / 1_000),
+                ),
+              }
+            : headers,
+        );
       }
-      return json({ error: { code: "INVALID_REQUEST" } }, 400, headers);
+      logInternalHttpError(requestId);
+      return json(
+        { error: { code: "INTERNAL_ERROR", requestId } },
+        500,
+        headers,
+      );
     }
   }),
 });
@@ -209,6 +273,13 @@ http.route({
           edgeHeadersAvailable:
             proxyRequestTrusted && Object.keys(geoFromHeaders(request)).length > 0,
         },
+        features: {
+          botDetection: "userAgent",
+          uniqueVisitors:
+            clientIp.ip && (metadata.userAgent ?? request.headers.get("user-agent"))
+              ? "dailyHash"
+              : "session",
+        },
       },
       200,
       {
@@ -458,45 +529,45 @@ function decodeHeader(value: string | undefined): string | undefined {
   }
 }
 
-function classifyUserAgent(userAgent: string): {
-  browser: string;
-  os: string;
-  device: string;
-} {
-  const browser = /Edg\//.test(userAgent)
-    ? "Edge"
-    : /Firefox\//.test(userAgent)
-      ? "Firefox"
-      : /Chrome\//.test(userAgent)
-        ? "Chrome"
-        : /Safari\//.test(userAgent)
-          ? "Safari"
-          : "Other";
-  const os = /Android/.test(userAgent)
-    ? "Android"
-    : /iPhone|iPad/.test(userAgent)
-      ? "iOS"
-      : /Windows/.test(userAgent)
-        ? "Windows"
-        : /Mac OS X/.test(userAgent)
-          ? "macOS"
-          : /Linux/.test(userAgent)
-            ? "Linux"
-            : "Other";
-  const device = /iPad|Tablet/.test(userAgent)
-    ? "tablet"
-    : /Mobile|Android|iPhone/.test(userAgent)
-      ? "mobile"
-      : "desktop";
-  return { browser, os, device };
+type GeoIpFailureStage = "claim" | "resolve" | "apply";
+
+function logInternalHttpError(requestId: string): void {
+  console.error(JSON.stringify({
+    level: "error",
+    event: "rastro.http.internal_error",
+    requestId,
+    route: "/events",
+    method: "POST",
+  }));
+}
+
+function logGeoIpFailure(
+  requestId: string,
+  stage: GeoIpFailureStage,
+  provider: "ipinfo" | "ipwhois",
+): void {
+  console.warn(JSON.stringify({
+    level: "warn",
+    event: "rastro.geoip.failure",
+    requestId,
+    route: "/events",
+    stage,
+    provider,
+  }));
+}
+
+function requestIdHeaders(requestId: string): Record<string, string> {
+  return { "X-Request-ID": requestId };
 }
 
-function corsHeaders(origin: string): HeadersInit {
+function corsHeaders(origin: string, requestId?: string): Record<string, string> {
   return {
     "Access-Control-Allow-Origin": origin,
     "Access-Control-Allow-Methods": "POST, OPTIONS",
     "Access-Control-Allow-Headers": "Content-Type",
+    "Access-Control-Expose-Headers": "X-Request-ID, Retry-After",
     "Access-Control-Max-Age": "86400",
+    ...(requestId ? requestIdHeaders(requestId) : {}),
     Vary: "Origin",
   };
 }
@@ -509,3 +580,23 @@ function json(value: unknown, status: number, headers?: HeadersInit): Response {
 }
 
 export default http;
+
+let cachedVisitorSecret: string | undefined;
+
+/** The per-deployment salt behind anonymous visitor keys, created on first use. */
+async function visitorSecret(ctx: {
+  runQuery: (reference: typeof internal.identity.secret, args: Record<string, never>) => Promise<string | null>;
+  runMutation: (
+    reference: typeof internal.identity.ensureSecret,
+    args: { candidate: string },
+  ) => Promise<string>;
+}): Promise<string> {
+  if (cachedVisitorSecret) return cachedVisitorSecret;
+  const stored = await ctx.runQuery(internal.identity.secret, {});
+  cachedVisitorSecret =
+    stored ??
+    (await ctx.runMutation(internal.identity.ensureSecret, {
+      candidate: randomSecret(),
+    }));
+  return cachedVisitorSecret;
+}

package/src/component/identity.ts

@@ -0,0 +1,74 @@
+import { v } from "convex/values";
+import { DAY_MS } from "./constants.js";
+import { internalMutation, internalQuery } from "./_generated/server.js";
+
+/**
+ * Anonymous visitors (no host-supplied id) are counted through a salted hash of
+ * the request IP and User-Agent that rotates every UTC day. The hash is derived
+ * in the HTTP action, so the raw IP never reaches a mutation or a table, and the
+ * salt is a per-deployment secret, so nobody holding a key can walk the IPv4
+ * space back to an address. Same device and network on the same day count once;
+ * the next day they are a new visitor by design.
+ */
+const KEY_HEX_LENGTH = 24;
+const SECRET_PATTERN = /^[0-9a-f]{64}$/;
+
+export const secret = internalQuery({
+  args: {},
+  returns: v.union(v.string(), v.null()),
+  handler: async (ctx) => {
+    const row = await ctx.db
+      .query("visitorSecrets")
+      .withIndex("by_key", (range) => range.eq("key", "current"))
+      .unique();
+    return row?.value ?? null;
+  },
+});
+
+export const ensureSecret = internalMutation({
+  args: { candidate: v.string() },
+  returns: v.string(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("visitorSecrets")
+      .withIndex("by_key", (range) => range.eq("key", "current"))
+      .unique();
+    if (existing) return existing.value;
+    if (!SECRET_PATTERN.test(args.candidate)) {
+      throw new Error("visitor secret candidate must be 64 hex characters");
+    }
+    await ctx.db.insert("visitorSecrets", {
+      key: "current",
+      value: args.candidate,
+      createdAt: Date.now(),
+    });
+    return args.candidate;
+  },
+});
+
+export function randomSecret(): string {
+  return hex(crypto.getRandomValues(new Uint8Array(32)));
+}
+
+export async function deriveVisitorKey(input: {
+  secret: string;
+  now: number;
+  siteId: string;
+  ip: string;
+  userAgent: string;
+}): Promise<string> {
+  const dayStart = Math.floor(input.now / DAY_MS) * DAY_MS;
+  const material = new TextEncoder().encode(
+    [input.secret, dayStart, input.siteId, input.ip, input.userAgent].join(" "),
+  );
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", material),
+  );
+  return hex(digest).slice(0, KEY_HEX_LENGTH);
+}
+
+function hex(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(
+    "",
+  );
+}