@cosmicdrift/kumiko-bundled-features 0.319.0 → 0.320.0

package/src/user-data-rights/__tests__/download-by-token-ip-bucket.integration.test.ts

@@ -0,0 +1,170 @@
+// #1307 regression: the `/user-export/by-token` httpRoute wrapper re-dispatches
+// to `download-by-token` (rateLimit: { per: "ip", limit: 30 }) via an internal
+// `app.fetch(new Request(...))` call. That internal request has no socket of
+// its own, so the L3 per-ip bucket only sees a real client IP if the wrapper
+// hands it one explicitly. Before the fix it forwarded a synthetic single-hop
+// X-Forwarded-For header — which the shared client-ip resolver only honours
+// at exactly `trustedProxyHops: 1` (see client-ip.ts). At the framework
+// default (0) the header is ignored outright, and at >=2 a single-entry XFF
+// is always short, so both cases fell back to the shared "unknown" bucket:
+// one caller could exhaust the 30/min cap for every anonymous downloader.
+// The fix passes the already-resolved `clientIp` straight through as the
+// internal request's env (2nd `app.fetch` arg), independent of hop count.
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { createConfigAccessorFactory } from "../../config/feature";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createDataRetentionFeature } from "../../data-retention";
+import { fileFoundationFeature } from "../../file-foundation";
+import { fileProviderInMemoryFeature } from "../../file-provider-inmemory";
+import { createSessionsFeature } from "../../sessions";
+import { createUserFeature } from "../../user";
+import { createUserDataRightsFeature } from "../feature";
+import { exportDownloadTokenEntity } from "../schema/download-token";
+import { exportJobEntity } from "../schema/export-job";
+
+const tenant = testTenantId(1);
+
+async function buildStack(trustedProxyHops: number): Promise<TestStack> {
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  const resolver = createConfigResolver({ cipher: encryption });
+
+  const stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      fileFoundationFeature,
+      fileProviderInMemoryFeature,
+      authFoundationFeature,
+      createSessionsFeature(),
+      createUserDataRightsFeature(),
+    ],
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      configEncryption: encryption,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    }),
+    anonymousAccess: { defaultTenantId: tenant },
+    trustedProxyHops,
+  });
+  await unsafeCreateEntityTable(stack.db, exportJobEntity);
+  await unsafeCreateEntityTable(stack.db, exportDownloadTokenEntity);
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+  await unsafePushTables(stack.db, { configValuesTable });
+  await asRawClient(stack.db).unsafe(`
+    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      tenant_id UUID NOT NULL,
+      user_id TEXT NOT NULL,
+      version INTEGER NOT NULL DEFAULT 0,
+      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      modified_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      inserted_by_id TEXT,
+      modified_by_id TEXT,
+      is_deleted BOOLEAN NOT NULL DEFAULT false,
+      deleted_at TIMESTAMPTZ,
+      deleted_by_id TEXT,
+      roles TEXT NOT NULL DEFAULT '[]',
+      UNIQUE(user_id, tenant_id)
+    )
+  `);
+  return stack;
+}
+
+// Rate-limit runs before the handler body (dispatch-query.ts: feature-gate →
+// rate-limit → access → validation → handler), so a garbage token still
+// consumes the bucket and lets the test avoid seeding a real export job —
+// each call 404s (download.notFound) until the bucket is exhausted, then 429.
+async function postByToken(
+  stack: TestStack,
+  headers: Record<string, string>,
+  socketAddress?: string,
+): Promise<Response> {
+  const request = new Request("http://test/user-export/by-token", {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify({ token: "not-a-real-token" }),
+  });
+  return socketAddress ? stack.app.fetch(request, socketAddress) : stack.app.fetch(request);
+}
+
+async function exhaustBucket(
+  stack: TestStack,
+  headers: Record<string, string>,
+  socketAddress?: string,
+): Promise<void> {
+  for (let i = 0; i < 30; i++) {
+    const res = await postByToken(stack, headers, socketAddress);
+    expect(res.status).toBe(404);
+  }
+}
+
+describe("download-by-token IP bucket — trustedProxyHops: 0 (socket-only)", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await buildStack(0);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("two distinct callers each get their own 30/min bucket, not a shared one", async () => {
+    // hops=0 ignores X-Forwarded-For outright — distinct callers are
+    // simulated via distinct socket addresses (2nd app.fetch arg) on the
+    // OUTER request; a spoofed XFF must have no effect at all.
+    const spoofedHeaders = { "x-forwarded-for": "ignored-at-hops-0" };
+    await exhaustBucket(stack, spoofedHeaders, "203.0.113.10");
+    const blocked = await postByToken(stack, spoofedHeaders, "203.0.113.10");
+    expect(blocked.status).toBe(429);
+
+    // A second caller (different socket) must not inherit caller A's
+    // exhausted bucket, even though it sends the exact same forged XFF.
+    const first = await postByToken(stack, spoofedHeaders, "203.0.113.20");
+    expect(first.status).toBe(404);
+  });
+});
+
+describe("download-by-token IP bucket — trustedProxyHops: 2", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await buildStack(2);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("two distinct callers (resolved via a 2-hop XFF chain) each get their own bucket", async () => {
+    // entries[length-hops] is the real client: index 1 of a 3-entry chain.
+    const callerA = { "x-forwarded-for": "client-forged, 10.1.1.1, 10.0.0.9" };
+    const callerB = { "x-forwarded-for": "client-forged, 10.2.2.2, 10.0.0.9" };
+
+    await exhaustBucket(stack, callerA);
+    const blocked = await postByToken(stack, callerA);
+    expect(blocked.status).toBe(429);
+
+    const first = await postByToken(stack, callerB);
+    expect(first.status).toBe(404);
+  });
+});

package/src/user-data-rights/__tests__/download.integration.test.ts

@@ -134,6 +134,9 @@ beforeAll(async () => {
     anonymousAccess: {
       defaultTenantId: tenantA,
     },
+    // "download-by-job" below asserts the literal ip stored by requestContext,
+    // so the resolver needs a trusted hop to read x-forwarded-for at all.
+    trustedProxyHops: 1,
   });
   await unsafeCreateEntityTable(stack.db, exportJobEntity);
   await unsafeCreateEntityTable(stack.db, exportDownloadTokenEntity);
@@ -383,10 +386,10 @@ describe("download-by-job :: happy path", () => {
   test("session-auth: Job-Owner → returns signed URL + audit (IP aus X-Forwarded-For)", async () => {
     const { jobId } = await seedDoneJobWithToken();
 
-    // Der UI-Klick laeuft als direkter download-by-job-Query (Client traegt
-    // X-CSRF-Token). Die Audit-IP kommt server-trusted aus dem RequestContext
-    // (X-Forwarded-For, erster Hop), nicht aus einem vom Client mitgeschickten
-    // Feld.
+    // The UI click runs as a direct download-by-job query (client sends
+    // X-CSRF-Token). The audit IP is server-trusted from the RequestContext
+    // (X-Forwarded-For entry appended by the trusted proxy at
+    // trustedProxyHops=1), never from a client-supplied field.
     const res = await stack.http.queryWithHeaders(
       "user-data-rights:query:download-by-job",
       { jobId },
@@ -403,7 +406,7 @@ describe("download-by-job :: happy path", () => {
       lastUsedFromIp: string | null;
     }>;
     expect(row?.useCount).toBe(1);
-    expect(row?.lastUsedFromIp).toBe("10.0.0.5");
+    expect(row?.lastUsedFromIp).toBe("10.0.0.1");
   });
 
   test("failed Job (status != done) → 404 download.unavailable (job-Pfad)", async () => {
@@ -485,6 +488,8 @@ describe("r.httpRoute :: /user-export/by-token (Magic-Link e2e)", () => {
   test("POST-Exchange (Fragment-Pfad): happy-path + IP/UA-Audit aus httpRoute-Headers", async () => {
     const { jobId, plainToken } = await seedDoneJobWithToken();
 
+    // trustedProxyHops=1 here → the resolver trusts the last XFF entry, not
+    // the client-spoofable first one.
     const res = await stack.app.fetch(
       new Request("http://test/user-export/by-token", {
         method: "POST",
@@ -506,7 +511,8 @@ describe("r.httpRoute :: /user-export/by-token (Magic-Link e2e)", () => {
       lastUsedUserAgent: string | null;
     }>;
     expect(row?.useCount).toBe(1);
-    expect(row?.lastUsedFromIp).toBe("203.0.113.9");
+    expect(row?.lastUsedFromIp).toBe("10.0.0.1");
+    expect(row?.lastUsedFromIp).not.toBe("203.0.113.9");
     expect(row?.lastUsedUserAgent).toBe("e2e-test/3.0");
   });
 

package/src/user-data-rights/__tests__/extract-audit-meta.test.ts

@@ -0,0 +1,36 @@
+// extractAuditMeta takes the framework-resolved clientIp instead of reading
+// X-Forwarded-For itself, so a caller can't plant a fake audit IP.
+import { describe, expect, test } from "bun:test";
+import { UNKNOWN_CLIENT_IP } from "@cosmicdrift/kumiko-framework/api";
+import { extractAuditMeta } from "../feature";
+
+describe("extractAuditMeta", () => {
+  test("uses the resolved clientIp, ignoring a spoofed X-Forwarded-For header on the same request", () => {
+    const headers = new Headers({
+      "x-forwarded-for": "203.0.113.1, 10.0.0.1",
+      "x-real-ip": "203.0.113.1",
+      "user-agent": "test-agent",
+    });
+
+    const auditMeta = extractAuditMeta(headers, "198.51.100.7");
+
+    expect(auditMeta.ip).toBe("198.51.100.7");
+    expect(auditMeta.ip).not.toBe("203.0.113.1");
+    expect(auditMeta.userAgent).toBe("test-agent");
+  });
+
+  test("maps the resolver's unknown sentinel to null instead of storing the literal string", () => {
+    const auditMeta = extractAuditMeta(new Headers(), UNKNOWN_CLIENT_IP);
+
+    expect(auditMeta.ip).toBeNull();
+  });
+
+  test("reads user-agent from headers independently of the resolved IP", () => {
+    const auditMeta = extractAuditMeta(
+      new Headers({ "user-agent": "spoofable-but-fine" }),
+      "1.2.3.4",
+    );
+
+    expect(auditMeta.userAgent).toBe("spoofable-but-fine");
+  });
+});

package/src/user-data-rights/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "Audit IP comes from the framework's trustedProxyHops-aware resolver, not a self-parsed X-Forwarded-For",
+    "detail": "`extractAuditMeta` no longer reads `X-Forwarded-For`/`X-Real-IP` itself —\nit takes the `clientIp` the `/user-export/by-token` httpRoute handler now\nreceives from `HttpRouteHandlerDeps`, mapping the resolver's `unknown`\nsentinel to `null`. Closes the spoofed-first-XFF-entry gap for that\nroute. A caller invoking `/api/query`'s `download-by-token` handler\ndirectly (not through this httpRoute) can still pass its own `auditMeta`\nin the payload — a pre-existing, documented tradeoff (the handler's own\ncomment: audit data isn't security-relevant), unchanged by this fix."
+  },
   {
     "version": "0.313.0",
     "type": "fix",

package/src/user-data-rights/feature.ts

@@ -1,4 +1,5 @@
 // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312 (feature.ts > 300 lines)
+import { UNKNOWN_CLIENT_IP } from "@cosmicdrift/kumiko-framework/api";
 import {
   createSystemConfig,
   defineFeature,
@@ -486,10 +487,11 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
     // as a POST body instead of a query string (issue #1271). A dedicated
     // route rather than letting the browser JS call /api/query directly,
     // for two reasons:
-    //   1. IP/UA audit — extractAuditMeta needs the raw request headers,
-    //      which only the server has, not the browser (see the GET path
-    //      above). Without this route every fragment-path download would
-    //      land in download-attempt with lastUsedFromIp/UA = null.
+    //   1. IP/UA audit — extractAuditMeta needs the raw request headers and
+    //      the framework-resolved client IP, which only the server has, not
+    //      the browser (see the GET path above). Without this route every
+    //      fragment-path download would land in download-attempt with
+    //      lastUsedFromIp/UA = null.
     //   2. /api/query is the reserved dispatcher namespace for
     //      authenticated writes/queries — an anonymous cross-origin POST
     //      there isn't guaranteed to be reachable (origin guard).
@@ -497,7 +499,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
       method: "POST",
       path: "/user-export/by-token",
       anonymous: true,
-      handler: async (c, { app }) => {
+      handler: async (c, { app, clientIp }) => {
         const url = new URL(c.req.url);
         const parsedBody = await c.req.json().catch(() => null);
         const token =
@@ -507,28 +509,29 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         if (typeof token !== "string" || token.length === 0) {
           return c.json({ error: "missing_token" }, 400);
         }
-        const auditMeta = extractAuditMeta(c.req.raw.headers);
+        const auditMeta = extractAuditMeta(c.req.raw.headers, clientIp);
         return app.fetch(
           new Request(`${url.origin}/api/query`, {
             method: "POST",
-            headers: {
-              "content-type": "application/json",
-              // download-by-token.query.ts's `rateLimit: { per: "ip", limit: 30 }`
-              // keys off request-id-middleware's own x-forwarded-for read on
-              // THIS internal request — without forwarding it, every fragment-
-              // POST download shares the request's own (empty/localhost) IP,
-              // turning the per-user 30/min backstop into one global bucket
-              // (#1307). Forwarding the same value extractAuditMeta already
-              // computed from the original request's headers doesn't widen the
-              // trust boundary: it's the identical XFF-trusts-first-hop model
-              // request-id-middleware.ts already applies framework-wide.
-              ...(auditMeta.ip ? { "x-forwarded-for": auditMeta.ip } : {}),
-            },
+            headers: { "content-type": "application/json" },
             body: JSON.stringify({
               type: "user-data-rights:query:download-by-token",
               payload: { token, auditMeta },
             }),
           }),
+          // download-by-token.query.ts's `rateLimit: { per: "ip", limit: 30 }`
+          // resolves the client IP from this internal request's env (2nd
+          // app.fetch arg), same as Bun.serve's socket address — without it,
+          // the resolver has neither a trusted XFF entry (trustedProxyHops
+          // defaults to 0, ignoring headers entirely) nor a socket, so every
+          // fragment-POST download would fall to the shared "unknown" bucket,
+          // turning the per-user 30/min backstop into one global bucket an
+          // attacker can exhaust for everyone (#1307). Passing `clientIp`
+          // directly as env — the same server-resolved, trustedProxyHops-
+          // aware value the outer request already trusted — reaches
+          // extractSocketAddress() without going through header/hop-count
+          // logic at all.
+          clientIp,
         );
       },
     });
@@ -727,24 +730,19 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
   });
 }
 
-// Extract Audit-Meta (IP + UA) aus den HTTP-Headers + steck es in die
-// query-payload. Der httpRoute-Wrapper ist trusted-source — er hat den
-// raw-request gesehen, nicht der direkter /api/query-Caller. User der
-// /api/query direkt mit eigenem auditMeta aufruft kann luegen, aber
-// auditMeta ist nicht security-relevant (operator kann mit server-logs
-// crossreferencen wenn forensik gebraucht).
-function extractAuditMeta(headers: Headers): { ip: string | null; userAgent: string | null } {
-  const xff = headers.get("x-forwarded-for");
-  let ip: string | null = null;
-  if (xff) {
-    const first = xff.split(",")[0]?.trim();
-    if (first && first.length > 0) ip = first;
-  }
-  if (!ip) {
-    const real = headers.get("x-real-ip");
-    if (real && real.length > 0) ip = real;
-  }
-  return { ip, userAgent: headers.get("user-agent") };
+// `clientIp` comes from the server's trustedProxyHops-aware resolver instead
+// of reading X-Forwarded-For here, where a forged first entry would spoof the
+// audit IP. A caller hitting /api/query directly (bypassing this httpRoute
+// wrapper) with its own auditMeta can still lie — accepted, see
+// download-by-token.query.ts.
+export function extractAuditMeta(
+  headers: Headers,
+  clientIp: string,
+): { ip: string | null; userAgent: string | null } {
+  return {
+    ip: clientIp === UNKNOWN_CLIENT_IP ? null : clientIp,
+    userAgent: headers.get("user-agent"),
+  };
 }
 
 // Interstitial page for the magic-link fragment exchange (see the