@podosoft/podokit 1.1.6 → 1.2.0

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.module.ts

@@ -1,44 +1,62 @@
 import { Elysia, t } from "elysia";
-import { OBJECT_STORAGE } from "@podosoft/podokit-runtime";
+import { OBJECT_STORAGE, objectResponse } from "@podosoft/podokit-runtime";
 import { PROVIDERS } from "../config/providers";
 import {
   type AppPlugin,
+  type ElysiaPlugin,
   type PodokitModule,
   READINESS,
+  REQUEST_IDENTITY,
+  type RequestIdentity,
   type ServiceKey,
 } from "../core/services";
 import { StorageService } from "./storage.service";
 import { S3ObjectStore } from "./s3-object.store";
+import {
+  demoKeyParams,
+  demoObjectKey,
+  storageObjectNotFound,
+  requireStorageAdmin,
+} from "./storage-demo";
 
 export const STORAGE = Symbol("storage") as ServiceKey<StorageService>;
 
-const storagePlugin: AppPlugin = ({ services }) => {
-  if (PROVIDERS["object-storage"] !== "s3") {
-    return new Elysia({ name: "podokit.storage-s3.inactive" });
-  }
-  const storage = services.resolve(STORAGE);
+export type DemoStorage = Pick<StorageService, "put" | "open" | "presignedGetUrl">;
+
+export function storageDemoRoutes(storage: DemoStorage, identity: RequestIdentity): ElysiaPlugin {
   return new Elysia({ name: "podokit.storage" })
-    .put("/storage/:key", async ({ params, body }) => {
-      await storage.put(params.key, body.content, "text/plain");
+    .put("/storage/:key", async ({ request, params, body }) => {
+      await requireStorageAdmin(identity, request);
+      await storage.put(demoObjectKey(params.key), body.content, "text/plain");
       return { key: params.key };
     }, {
-      params: t.Object({ key: t.String({ minLength: 1 }) }),
+      params: demoKeyParams,
       body: t.Object({ content: t.String() }),
-      detail: { tags: ["storage"], summary: "Store an object" },
+      detail: { tags: ["storage"], summary: "Store a demo object (administrators only)" },
     })
-    .get("/storage/:key/presigned", async ({ params }) => ({
-      url: await storage.presignedGetUrl(params.key),
-    }), {
-      params: t.Object({ key: t.String({ minLength: 1 }) }),
-      detail: { tags: ["storage"], summary: "Presign an object download" },
+    .get("/storage/:key/presigned", async ({ request, params }) => {
+      await requireStorageAdmin(identity, request);
+      return { url: await storage.presignedGetUrl(demoObjectKey(params.key)) };
+    }, {
+      params: demoKeyParams,
+      detail: { tags: ["storage"], summary: "Presign a demo object download (administrators only)" },
     })
-    .get("/storage/:key", async ({ params }) => ({
-      key: params.key,
-      content: (await storage.get(params.key)).toString("utf8"),
-    }), {
-      params: t.Object({ key: t.String({ minLength: 1 }) }),
-      detail: { tags: ["storage"], summary: "Read an object" },
+    .get("/storage/:key", async ({ request, params }) => {
+      await requireStorageAdmin(identity, request);
+      const object = await storage.open(demoObjectKey(params.key));
+      if (!object) throw storageObjectNotFound();
+      return objectResponse(request, object, { headers: { "x-content-type-options": "nosniff" } });
+    }, {
+      params: demoKeyParams,
+      detail: { tags: ["storage"], summary: "Read a demo object (administrators only)" },
     });
+}
+
+const storagePlugin: AppPlugin = ({ services }) => {
+  if (PROVIDERS["object-storage"] !== "s3") {
+    return new Elysia({ name: "podokit.storage-s3.inactive" });
+  }
+  return storageDemoRoutes(services.resolve(STORAGE), services.resolve(REQUEST_IDENTITY));
 };
 
 export const storageModule: PodokitModule = {

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.service.ts

@@ -1,7 +1,70 @@
-import { S3Client } from "bun";
+import { S3Client, type S3Stats } from "bun";
+import {
+  objectListLimit,
+  type ListObjectsOptions,
+  type ObjectData,
+  type ObjectInfo,
+  type ObjectPage,
+} from "@podosoft/podokit-runtime";
 import { ReadinessService } from "../health/readiness.service";
 import { storageSettings } from "./storage.config";
 
+function isMissingObject(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "NoSuchKey";
+}
+
+function entityTag(etag: string): string {
+  return etag.startsWith("\"") || etag.startsWith("W/\"") ? etag : `"${etag}"`;
+}
+
+function objectInfo(key: string, stats: S3Stats): ObjectInfo {
+  return {
+    key,
+    size: stats.size,
+    ...(stats.type ? { contentType: stats.type } : {}),
+    etag: entityTag(stats.etag),
+    lastModified: stats.lastModified,
+  };
+}
+
+/**
+ * Downloads on the first read, so an unread body costs no request. Bun's
+ * `S3File.stream()` reads ahead without backpressure and would hold the rest of
+ * the object for a slow client; a presigned GET through fetch is paced by the
+ * socket instead, and If-Match keeps it on the version that was described.
+ */
+function download(client: S3Client, key: string, etag: string): ReadableStream<Uint8Array> {
+  const abort = new AbortController();
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller): Promise<void> {
+      if (!reader) {
+        const response = await fetch(client.presign(key, { expiresIn: 60 }), {
+          headers: { "if-match": etag },
+          decompress: false,
+          signal: abort.signal,
+        });
+        if (!response.ok || !response.body) {
+          await response.body?.cancel();
+          throw new Error(
+            response.status === 404 || response.status === 412
+              ? `Object ${key} changed while it was being read`
+              : `Object ${key} download failed with status ${response.status}`,
+          );
+        }
+        reader = response.body.getReader();
+      }
+      const next = await reader.read();
+      if (next.done) controller.close();
+      else controller.enqueue(next.value);
+    },
+    async cancel(reason): Promise<void> {
+      abort.abort(reason);
+      await reader?.cancel(reason).catch(() => undefined);
+    },
+  }, { highWaterMark: 0 });
+}
+
 export class StorageService {
   private readonly client: S3Client;
   private unregisterReadiness?: () => void;
@@ -25,8 +88,44 @@ export class StorageService {
     await this.client.file(key).write(body, contentType ? { type: contentType } : undefined);
   }
 
+  /** Reads a whole object into memory. Use `open()` for anything that can be large. */
   async get(key: string): Promise<Buffer> {
-    return Buffer.from(await this.client.file(key).bytes());
+    const bytes = await this.client.file(key).bytes();
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  }
+
+  /** Object metadata, or null when the key does not exist. */
+  async stat(key: string): Promise<ObjectInfo | null> {
+    try {
+      return objectInfo(key, await this.client.file(key).stat());
+    } catch (error) {
+      if (isMissingObject(error)) return null;
+      throw error;
+    }
+  }
+
+  /**
+   * Metadata plus a streamed body, or null when the key does not exist. The
+   * metadata request comes first because a missing key would otherwise only
+   * fail the stream, after a response has already started.
+   */
+  async open(key: string): Promise<ObjectData | null> {
+    const info = await this.stat(key);
+    if (!info) return null;
+    return { ...info, body: download(this.client, key, info.etag) };
+  }
+
+  /** One page of the keys under `prefix`; the bucket is never listed in full. */
+  async list(prefix: string, options: ListObjectsOptions = {}): Promise<ObjectPage> {
+    const page = await this.client.list({
+      prefix,
+      maxKeys: objectListLimit(options),
+      ...(options.cursor ? { continuationToken: options.cursor } : {}),
+    });
+    const keys = (page.contents ?? []).map((object) => object.key);
+    return page.isTruncated && page.nextContinuationToken
+      ? { keys, nextCursor: page.nextContinuationToken }
+      : { keys };
   }
 
   async exists(key: string): Promise<boolean> {

package/dist/templates/modules/object-storage-s3/files/tests/api/storage.api.spec.ts

@@ -1,19 +1,50 @@
-import { expect, test } from "@playwright/test";
+import { expect, test, type APIRequestContext, type PlaywrightWorkerArgs } from "@playwright/test";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
+// The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
+// spec also compiles in apps that do not install that module.
+const admin = {
+  email: "admin@example.com",
+  password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
+};
 
-async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]): Promise<import("@playwright/test").APIRequestContext> {
-  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+type Playwright = PlaywrightWorkerArgs["playwright"];
+
+function uniqueKey(): string {
+  return `obj-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function newContext(playwright: Playwright): Promise<APIRequestContext> {
+  return playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+}
+
+async function sessionRoles(ctx: APIRequestContext): Promise<string[] | undefined> {
+  const response = await ctx.get("/api/auth/get-session");
+  if (!response.ok()) return undefined;
+  const session = await response.json() as { user?: { role?: string | null } } | null;
+  if (!session?.user) return undefined;
+  return (session.user.role ?? "").split(",").map((role) => role.trim()).filter(Boolean);
+}
+
+/** Resolves false when the auth module is missing or sign-up does not start a session. */
+async function signUp(ctx: APIRequestContext): Promise<boolean> {
   const email = `storage-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
-  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "S" } }).catch(() => undefined);
-  return ctx;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "S" } });
+  return (await sessionRoles(ctx)) !== undefined;
+}
+
+/** Resolves false when no administrator session is available. */
+async function signInAdmin(ctx: APIRequestContext): Promise<boolean> {
+  const response = await ctx.post("/api/auth/sign-in/email", { data: admin });
+  return response.ok() && ((await sessionRoles(ctx)) ?? []).includes("admin");
 }
 
 test("object storage: put, get, and presign @smoke", async ({ playwright }) => {
-  const ctx = await session(playwright);
-  const key = `obj-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const ctx = await newContext(playwright);
+  const key = uniqueKey();
   try {
+    test.skip(!(await signInAdmin(ctx)), "requires the auth module and the seeded administrator");
     const put = await ctx.put(`/api/storage/${key}`, { data: { content: "hello world" } });
     test.skip(!process.env.S3_ENDPOINT && put.status() >= 500, "optional S3-compatible service not configured");
     expect(put.ok()).toBeTruthy();
@@ -21,12 +52,20 @@ test("object storage: put, get, and presign @smoke", async ({ playwright }) => {
 
     const read = await ctx.get(`/api/storage/${key}`);
     expect(read.ok()).toBeTruthy();
-    expect(await read.json()).toMatchObject({ key, content: "hello world" });
+    expect(read.headers()["content-type"]).toContain("text/plain");
+    expect(read.headers()["content-length"]).toBe("11");
+    expect(read.headers()["last-modified"]).toBeTruthy();
+    const etag = read.headers()["etag"];
+    expect(etag).toMatch(/^"[^"]+"$/);
+    expect(await read.text()).toBe("hello world");
+
+    const revalidated = await ctx.get(`/api/storage/${key}`, { headers: { "if-none-match": etag ?? "" } });
+    expect(revalidated.status()).toBe(304);
 
     const presigned = await ctx.get(`/api/storage/${key}/presigned`);
     expect(presigned.ok()).toBeTruthy();
     const pre = await presigned.json() as { url: string };
-    expect(new URL(pre.url).pathname).toContain(key);
+    expect(new URL(pre.url, base).pathname).toContain(`demo/${key}`);
     // The URL is signed for the API's S3 endpoint. A containerized dev stack signs an
     // in-network host, so download it only when the runner was given that endpoint too.
     if (process.env.S3_ENDPOINT) {
@@ -38,3 +77,39 @@ test("object storage: put, get, and presign @smoke", async ({ playwright }) => {
     await ctx.dispose();
   }
 });
+
+test("object storage demo routes are limited to administrators", async ({ playwright }) => {
+  const anonymous = await newContext(playwright);
+  const user = await newContext(playwright);
+  const key = uniqueKey();
+  try {
+    test.skip(!(await signUp(user)), "requires the auth module");
+    const unauthenticated = await anonymous.put(`/api/storage/${key}`, { data: { content: "x" } });
+    expect(unauthenticated.status()).toBe(401);
+
+    for (const response of [
+      await user.put(`/api/storage/${key}`, { data: { content: "x" } }),
+      await user.get(`/api/storage/${key}`),
+      await user.get(`/api/storage/${key}/presigned`),
+    ]) {
+      expect(response.status()).toBe(403);
+      expect(await response.json()).toMatchObject({ error: { code: "ADMIN_REQUIRED" } });
+    }
+  } finally {
+    await anonymous.dispose();
+    await user.dispose();
+  }
+});
+
+test("object storage demo keys cannot reach other features' objects", async ({ playwright }) => {
+  const ctx = await newContext(playwright);
+  try {
+    test.skip(!(await signInAdmin(ctx)), "requires the auth module and the seeded administrator");
+    for (const key of ["site%2Ffavicon", "profile-images%2Fx.png", "..%2Fsite%2Ffavicon", ".podokit"]) {
+      const response = await ctx.put(`/api/storage/${key}`, { data: { content: "x" } });
+      expect([400, 404], `PUT /api/storage/${key}`).toContain(response.status());
+    }
+  } finally {
+    await ctx.dispose();
+  }
+});

package/dist/templates/modules/object-storage-s3/module.manifest.json

@@ -7,6 +7,9 @@
   "requiredProjectFiles": [
     "apps/api/src/health/readiness.service.ts"
   ],
+  "requiredProjectContents": {
+    "apps/api/src/core/services.ts": ["isAdmin(request: Request): Promise<boolean>;"]
+  },
   "targetApp": "api",
   "env": [
     "# object storage — STORAGE_PROVIDER: minio | aws",
@@ -24,9 +27,11 @@
   ],
   "instructions": [
     "Start Silo for local dev:  docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d",
-    "Store an object:  curl -XPUT localhost:5002/storage/hello -H 'content-type: application/json' -d '{\"content\":\"hi\"}'",
-    "Read it back:     curl localhost:5002/storage/hello",
-    "Presigned URL:    curl localhost:5002/storage/hello/presigned",
+    "The /storage demo routes need the auth module and an administrator session, and only reach keys under demo/.",
+    "Sign in as an administrator:  curl -c cookies.txt -XPOST localhost:5002/api/auth/sign-in/email -H 'content-type: application/json' -d '{\"email\":\"admin@example.com\",\"password\":\"<password>\"}'",
+    "Store an object:  curl -b cookies.txt -XPUT localhost:5002/storage/hello -H 'content-type: application/json' -d '{\"content\":\"hi\"}'",
+    "Read it back:     curl -b cookies.txt localhost:5002/storage/hello",
+    "Presigned URL:    curl -b cookies.txt localhost:5002/storage/hello/presigned",
     "For AWS S3: set STORAGE_PROVIDER=aws, remove S3_ENDPOINT, set S3_FORCE_PATH_STYLE=false and real credentials/bucket."
   ]
 }

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.config.spec.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import {
   clientAddressFromProxy,
   rateLimitConfig,
+  sessionSigningSecret,
 } from "./rate-limit.config";
 
 describe("rate limit configuration", () => {
@@ -88,4 +89,12 @@ describe("rate limit configuration", () => {
       }),
     ).toBe("10.0.0.9");
   });
+
+  test("reads the session signing secret the way the auth module does", () => {
+    expect(
+      sessionSigningSecret({ BETTER_AUTH_SECRET: "  session-secret-with-at-least-32-chars  " }),
+    ).toBe("session-secret-with-at-least-32-chars");
+    expect(sessionSigningSecret({ BETTER_AUTH_SECRET: "   " })).toBeUndefined();
+    expect(sessionSigningSecret({})).toBeUndefined();
+  });
 });

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.config.ts

@@ -84,6 +84,13 @@ export function rateLimitConfig(env: NodeJS.ProcessEnv = process.env): RateLimit
   };
 }
 
+// The secret Better Auth signs session cookies with (the auth module trims it the
+// same way). Without it, sessions are not recognized and requests are counted by
+// client address.
+export function sessionSigningSecret(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return env.BETTER_AUTH_SECRET?.trim() || undefined;
+}
+
 function normalizeIp(value: string | undefined): string | undefined {
   if (!value) return undefined;
   const trimmed = value.trim();

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.identity.spec.ts

@@ -1,4 +1,5 @@
-import { describe, expect, mock, test } from "bun:test";
+import { createHmac } from "node:crypto";
+import { describe, expect, mock, test, type Mock } from "bun:test";
 import { ApiKeyVerifier } from "../api-key/api-key-verifier";
 import {
   REQUEST_IDENTITY,
@@ -8,36 +9,130 @@ import {
   RATE_LIMIT_IDENTITY_EXTENSION,
   RateLimitIdentity,
   RateLimitIdentityExtension,
+  verifiedSessionToken,
 } from "./rate-limit.identity";
 
 const proxyConfig = { proxyHeader: "x-forwarded-for", trustedProxyHops: 1 };
+const secret = "rate-limit-test-secret-with-at-least-32-characters";
+const sessionToken = "Sx0d8mFqY3KcT7wJpLr2NvBhZa9EgUi4";
 
 function request(headers: Record<string, string> = {}): Request {
   return new Request("http://localhost/ordinary", { headers });
 }
 
-function services(userId?: string): ServiceRegistry {
+// The same format Better Auth issues: `${token}.${base64(HMAC-SHA256)}`.
+function signed(token: string, key = secret): string {
+  return `${token}.${createHmac("sha256", key).update(token).digest("base64")}`;
+}
+
+function tamperedSignature(value: string): string {
+  const index = value.lastIndexOf(".") + 1;
+  const replacement = value[index] === "A" ? "B" : "A";
+  return `${value.slice(0, index)}${replacement}${value.slice(index + 1)}`;
+}
+
+function sessionCookie(value: string, name = "better-auth.session_token"): string {
+  return `theme=dark; ${name}=${encodeURIComponent(value)}`;
+}
+
+function rejectingVerifier(): ApiKeyVerifier {
+  return { isValid: mock(() => false) } as unknown as ApiKeyVerifier;
+}
+
+// Registers a request identity that would hit the session store, so tests can
+// prove the limiter never asks for it.
+function servicesWithSessionStore(): {
+  registry: ServiceRegistry;
+  userId: Mock<(request: Request) => Promise<string | undefined>>;
+} {
   const registry = new ServiceRegistry();
-  registry.register(REQUEST_IDENTITY, { userId: async () => userId });
-  return registry;
+  const userId = mock(async (_request: Request): Promise<string | undefined> => "user-secret-id");
+  registry.register(REQUEST_IDENTITY, {
+    userId,
+    isAdmin: async () => false,
+    roles: async () => [],
+    activeOrganizationId: async () => undefined,
+  });
+  return { registry, userId };
 }
 
 describe("RateLimitIdentity", () => {
-  test("uses an authenticated user without exposing the user id", async () => {
-    const verifier = { isValid: mock(() => true) } as unknown as ApiKeyVerifier;
-    const identity = new RateLimitIdentity(verifier, services("user-secret-id"));
+  test("uses a verified session cookie without resolving the session", async () => {
+    const { registry, userId } = servicesWithSessionStore();
+    const identity = new RateLimitIdentity(rejectingVerifier(), registry, secret);
+
     const value = await identity.resolve(
-      request({ "x-api-key": "api-secret" }),
+      request({ cookie: sessionCookie(signed(sessionToken)) }),
+      "10.0.0.9",
+      proxyConfig,
+    );
+
+    expect(value).toMatch(/^session:[a-f0-9]{64}$/);
+    expect(value).not.toContain(sessionToken);
+    expect(userId).not.toHaveBeenCalled();
+  });
+
+  test("gives one session the same counter across cookie names and bearer forms", async () => {
+    const identity = new RateLimitIdentity(rejectingVerifier(), new ServiceRegistry(), secret);
+    const value = signed(sessionToken);
+    const resolved = await Promise.all([
+      identity.resolve(request({ cookie: sessionCookie(value) }), "10.0.0.9", proxyConfig),
+      identity.resolve(
+        request({ cookie: sessionCookie(value, "__Secure-better-auth.session_token") }),
+        "10.0.0.9",
+        proxyConfig,
+      ),
+      identity.resolve(request({ authorization: `Bearer ${value}` }), "10.0.0.9", proxyConfig),
+      identity.resolve(
+        request({ authorization: `bearer ${encodeURIComponent(value)}` }),
+        "10.0.0.9",
+        proxyConfig,
+      ),
+    ]);
+    expect(new Set(resolved).size).toBe(1);
+
+    const other = await identity.resolve(
+      request({ cookie: sessionCookie(signed("AnotherSessionToken0123456789abcd")) }),
       "10.0.0.9",
       proxyConfig,
     );
-    expect(value).toMatch(/^user:[a-f0-9]{64}$/);
-    expect(value).not.toContain("user-secret-id");
-    expect(verifier.isValid).not.toHaveBeenCalled();
+    expect(other).toMatch(/^session:/);
+    expect(other).not.toBe(resolved[0]);
+  });
+
+  test("counts forged, tampered, and unsigned session values by client address", async () => {
+    const identity = new RateLimitIdentity(rejectingVerifier(), new ServiceRegistry(), secret);
+    const address = { "x-forwarded-for": "203.0.113.7" };
+    const anonymous = await identity.resolve(request(address), "10.0.0.9", proxyConfig);
+    expect(anonymous).toMatch(/^ip:[a-f0-9]{64}$/);
+
+    const genuine = signed(sessionToken);
+    const forgedValues = [
+      signed(sessionToken, "an-attacker-chosen-secret-of-32-characters"),
+      `${sessionToken}x${genuine.slice(sessionToken.length)}`,
+      tamperedSignature(genuine),
+      genuine.replace("=", ""),
+      sessionToken,
+      "",
+    ];
+    for (const forged of forgedValues) {
+      const variants: Array<Record<string, string>> = [
+        { cookie: sessionCookie(forged) },
+        { authorization: `Bearer ${forged}` },
+      ];
+      for (const headers of variants) {
+        const value = await identity.resolve(
+          request({ ...address, ...headers }),
+          "10.0.0.9",
+          proxyConfig,
+        );
+        expect(value).toBe(anonymous);
+      }
+    }
   });
 
-  test("uses configured and extension API keys without storing raw keys", async () => {
-    const registry = services();
+  test("checks API keys before sessions without storing raw keys", async () => {
+    const registry = new ServiceRegistry();
     class Extension extends RateLimitIdentityExtension {
       async validatedApiKeyId(_request: Request, rawApiKey: string): Promise<string | undefined> {
         return rawApiKey === "external-valid" ? "external-stable-id" : undefined;
@@ -47,26 +142,49 @@ describe("RateLimitIdentity", () => {
     const verifier = {
       isValid: mock((value: string) => value === "configured-valid"),
     } as unknown as ApiKeyVerifier;
-    const identity = new RateLimitIdentity(verifier, registry);
+    const identity = new RateLimitIdentity(verifier, registry, secret);
+    const cookie = sessionCookie(signed(sessionToken));
 
     for (const raw of ["configured-valid", "external-valid"]) {
-      const value = await identity.resolve(request({ "x-api-key": raw }), "10.0.0.9", proxyConfig);
+      const value = await identity.resolve(
+        request({ "x-api-key": raw, cookie }),
+        "10.0.0.9",
+        proxyConfig,
+      );
       expect(value).toMatch(/^api-key:[a-f0-9]{64}$/);
       expect(value).not.toContain(raw);
     }
-  });
 
-  test("falls back to the trusted client address", async () => {
-    const identity = new RateLimitIdentity(
-      { isValid: mock(() => false) } as unknown as ApiKeyVerifier,
-      services(),
+    const invalidKey = await identity.resolve(
+      request({ "x-api-key": "invalid", cookie }),
+      "10.0.0.9",
+      proxyConfig,
     );
+    expect(invalidKey).toMatch(/^session:/);
+  });
+
+  test("falls back to the trusted client address without authentication", async () => {
+    const cookie = sessionCookie(signed(sessionToken));
+    // No session secret: the auth module is not installed or not configured.
+    const identity = new RateLimitIdentity(rejectingVerifier(), new ServiceRegistry(), undefined);
     const value = await identity.resolve(
-      request({ "x-forwarded-for": "203.0.113.7" }),
+      request({ "x-forwarded-for": "203.0.113.7", cookie }),
       "10.0.0.9",
       proxyConfig,
     );
     expect(value).toMatch(/^ip:[a-f0-9]{64}$/);
     expect(value).not.toContain("203.0.113.7");
+    expect(
+      await identity.resolve(request({ "x-forwarded-for": "203.0.113.7" }), "10.0.0.9", proxyConfig),
+    ).toBe(value);
+  });
+});
+
+describe("verifiedSessionToken", () => {
+  test("returns the token only for a matching signature", () => {
+    expect(verifiedSessionToken(signed(sessionToken), secret)).toBe(sessionToken);
+    expect(verifiedSessionToken(signed(sessionToken), `${secret}-rotated`)).toBeUndefined();
+    expect(verifiedSessionToken(".", secret)).toBeUndefined();
+    expect(verifiedSessionToken(`${sessionToken}.`, secret)).toBeUndefined();
   });
 });