@podosoft/podokit 1.1.6 → 1.2.0

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

@@ -1,10 +1,6 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import type { ApiKeyVerifier } from "../api-key/api-key-verifier";
-import {
-  REQUEST_IDENTITY,
-  type ServiceKey,
-  type ServiceRegistry,
-} from "../core/services";
+import type { ServiceKey, ServiceRegistry } from "../core/services";
 import {
   clientAddressFromProxy,
   type RateLimitConfig,
@@ -21,7 +17,20 @@ export const RATE_LIMIT_IDENTITY_EXTENSION = Symbol(
   "rate-limit-identity-extension",
 ) as ServiceKey<RateLimitIdentityExtension>;
 
-function stableDigest(kind: "user" | "api-key" | "ip", value: string): string {
+// Better Auth's session cookie. It adds the __Secure- prefix when BETTER_AUTH_URL
+// uses HTTPS; either name only counts when its signature verifies.
+const SESSION_COOKIE_NAMES = [
+  "__Secure-better-auth.session_token",
+  "better-auth.session_token",
+] as const;
+
+// better-call signs cookies as `${token}.${base64(HMAC-SHA256(secret, token))}` and
+// accepts only the padded 44-character standard base64 signature.
+const SIGNATURE = /^[A-Za-z0-9+/]{43}=$/;
+
+type TrackerKind = "session" | "api-key" | "ip";
+
+function stableDigest(kind: TrackerKind, value: string): string {
   return createHash("sha256")
     .update("podokit-rate-limit-v1", "utf8")
     .update("\0")
@@ -31,14 +40,56 @@ function stableDigest(kind: "user" | "api-key" | "ip", value: string): string {
     .digest("hex");
 }
 
-function tracker(kind: "user" | "api-key" | "ip", value: string): string {
+function tracker(kind: TrackerKind, value: string): string {
   return `${kind}:${stableDigest(kind, value)}`;
 }
 
+function decodeComponent(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function cookieValue(header: string | null, name: string): string | undefined {
+  if (!header) return undefined;
+  for (const pair of header.split(";")) {
+    const separator = pair.indexOf("=");
+    if (separator === -1 || pair.slice(0, separator).trim() !== name) continue;
+    const value = pair.slice(separator + 1).trim();
+    return decodeComponent(value.startsWith('"') ? value.slice(1, -1) : value);
+  }
+  return undefined;
+}
+
+function bearerValue(header: string | null): string | undefined {
+  if (!header || header.slice(0, 7).toLowerCase() !== "bearer ") return undefined;
+  const value = header.slice(7).trim();
+  return value.includes("%") ? decodeComponent(value) : value;
+}
+
+export function verifiedSessionToken(
+  signedValue: string,
+  secret: string,
+): string | undefined {
+  const separator = signedValue.lastIndexOf(".");
+  if (separator < 1) return undefined;
+  const token = signedValue.slice(0, separator);
+  const signature = signedValue.slice(separator + 1);
+  if (!SIGNATURE.test(signature)) return undefined;
+  const expected = createHmac("sha256", secret).update(token, "utf8").digest();
+  const provided = Buffer.from(signature, "base64");
+  return provided.length === expected.length && timingSafeEqual(provided, expected)
+    ? token
+    : undefined;
+}
+
 export class RateLimitIdentity {
   constructor(
     private readonly configuredApiKeys: ApiKeyVerifier,
     private readonly services: ServiceRegistry,
+    private readonly sessionSecret: string | undefined,
   ) {}
 
   async resolve(
@@ -46,9 +97,6 @@ export class RateLimitIdentity {
     remoteAddress: string | undefined,
     config: Pick<RateLimitConfig, "proxyHeader" | "trustedProxyHops">,
   ): Promise<string> {
-    const userId = await this.services.resolve(REQUEST_IDENTITY).userId(request);
-    if (userId) return tracker("user", userId);
-
     const rawApiKey = request.headers.get("x-api-key");
     if (rawApiKey) {
       if (this.configuredApiKeys.isValid(rawApiKey)) return tracker("api-key", rawApiKey);
@@ -57,7 +105,28 @@ export class RateLimitIdentity {
       if (additionalIdentity) return tracker("api-key", additionalIdentity);
     }
 
+    const sessionToken = this.sessionToken(request.headers);
+    if (sessionToken) return tracker("session", sessionToken);
+
     const clientAddress = clientAddressFromProxy(request.headers, remoteAddress, config);
     return tracker("ip", clientAddress);
   }
+
+  // Only the signature is checked: resolving the session would cost a database
+  // read on every request. A revoked or expired token still maps to its single
+  // counter, and a value without a valid signature falls back to the client address.
+  private sessionToken(headers: Headers): string | undefined {
+    if (!this.sessionSecret) return undefined;
+    const cookies = headers.get("cookie");
+    const candidates = [
+      bearerValue(headers.get("authorization")),
+      ...SESSION_COOKIE_NAMES.map((name) => cookieValue(cookies, name)),
+    ];
+    for (const candidate of candidates) {
+      if (!candidate) continue;
+      const token = verifiedSessionToken(candidate, this.sessionSecret);
+      if (token) return token;
+    }
+    return undefined;
+  }
 }

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

@@ -49,25 +49,31 @@ describe("RateLimiter", () => {
     }));
     const limiter = new RateLimiter(
       config,
-      { resolve: async () => "user:test" } as unknown as RateLimitIdentity,
+      { resolve: async () => "session:test" } as unknown as RateLimitIdentity,
       { increment } as RateLimitStorage,
     );
     await limiter.enforce(context("/ordinary").value);
     await limiter.enforce(context("/api/auth/sign-in", "POST").value);
     await limiter.enforce(context("/api/auth/get-session").value);
     await limiter.enforce(context("/site/settings").value);
+    await limiter.enforce(context("/api/auth/admin/list-users").value);
+    await limiter.enforce(context("/api/auth/admin/ban-user", "POST").value);
 
     expect(increment.mock.calls.map((call) => call.slice(1))).toEqual([
       [60],
       [60],
       [60],
       [60],
+      [60],
+      [60],
     ]);
     expect(increment.mock.calls.map((call) => call[0])).toEqual([
-      "podokit:test:rate-limit:general:user:test",
-      "podokit:test:rate-limit:auth:user:test",
-      "podokit:test:rate-limit:runtime:user:test",
-      "podokit:test:rate-limit:runtime:user:test",
+      "podokit:test:rate-limit:general:session:test",
+      "podokit:test:rate-limit:auth:session:test",
+      "podokit:test:rate-limit:runtime:session:test",
+      "podokit:test:rate-limit:runtime:session:test",
+      "podokit:test:rate-limit:general:session:test",
+      "podokit:test:rate-limit:auth:session:test",
     ]);
   });
 
@@ -131,7 +137,7 @@ describe("RateLimiter", () => {
     }));
     const limiter = new RateLimiter(
       config,
-      { resolve: async () => "user:test" } as unknown as RateLimitIdentity,
+      { resolve: async () => "session:test" } as unknown as RateLimitIdentity,
       { increment },
     );
     const headers: Record<string, string> = {};

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

@@ -7,7 +7,11 @@ import {
   type RequestGuardContext,
   type ServiceKey,
 } from "../core/services";
-import { rateLimitConfig, type RateLimitConfig } from "./rate-limit.config";
+import {
+  rateLimitConfig,
+  sessionSigningSecret,
+  type RateLimitConfig,
+} from "./rate-limit.config";
 import { RateLimitIdentity } from "./rate-limit.identity";
 
 export interface RateLimitIncrement {
@@ -101,6 +105,11 @@ export class RateLimiter {
     ) {
       return { name: "runtime", ttlSeconds: this.config.ttlSeconds, limit: this.config.runtimeLimit };
     }
+    // Admin reads need an admin session and are not credential attempts; the
+    // server-paged admin tables issue one per page, sort, or search.
+    if (method === "GET" && path.startsWith("/api/auth/admin/")) {
+      return { name: "general", ttlSeconds: this.config.ttlSeconds, limit: this.config.limit };
+    }
     if (path === "/api/auth" || path.startsWith("/api/auth/")) {
       return { name: "auth", ttlSeconds: this.config.authTtlSeconds, limit: this.config.authLimit };
     }
@@ -132,7 +141,11 @@ export const rateLimitModule: PodokitModule = {
   configure: (_env, services): void => {
     const limiter = new RateLimiter(
       rateLimitConfig(),
-      new RateLimitIdentity(services.resolve(API_KEY_VERIFIER), services),
+      new RateLimitIdentity(
+        services.resolve(API_KEY_VERIFIER),
+        services,
+        sessionSigningSecret(),
+      ),
       new CacheRateLimitStorage(services.resolve(CACHE)),
     );
     services.register(RATE_LIMITER, limiter);

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -65,6 +65,52 @@ test("rate limit: health probes stay available while ordinary routes return 429
   await ctx.dispose();
 });
 
+test("rate limit: each signed session has its own counter and forged sessions do not", async ({
+  playwright,
+}) => {
+  const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  const password = "Podokit3e-Str0ng!pw";
+  const first = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  expect((await first.post("/api/auth/sign-up/email", { data: { email, password, name: "Rate Limit" } })).ok()).toBeTruthy();
+  const probe = await first.get("/api/cache/rate-limit-probe");
+  test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
+  const remaining = (response: APIResponse): number => Number(response.headers()["ratelimit-remaining"]);
+  const ceiling = Number(probe.headers()["ratelimit-limit"]);
+  expect(remaining(probe)).toBe(ceiling - 1);
+
+  // The signed bearer form of the same session shares its counter.
+  const cookie = (await first.storageState()).cookies.find((c) => c.name.endsWith("session_token"));
+  expect(cookie, "sign-up set a session cookie").toBeTruthy();
+  const bearer = await playwright.request.newContext({
+    baseURL: base,
+    extraHTTPHeaders: { ...origin, authorization: `Bearer ${cookie?.value ?? ""}` },
+  });
+  expect(remaining(await bearer.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 2);
+
+  // Counters follow the session, not the user: signing in again starts a new one.
+  const second = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  expect((await second.post("/api/auth/sign-in/email", { data: { email, password } })).ok()).toBeTruthy();
+  expect(remaining(await second.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 1);
+
+  // A session cookie without a valid signature is counted with anonymous traffic
+  // from the same client address instead of receiving a fresh counter. The cache
+  // probe requires a session, so compare on a public route with the general limit.
+  const token = decodeURIComponent(cookie?.value ?? "").split(".")[0] ?? "";
+  const forged = await playwright.request.newContext({
+    baseURL: base,
+    extraHTTPHeaders: { ...origin, cookie: `${cookie?.name ?? ""}=${token}.${"A".repeat(43)}%3D` },
+  });
+  const anonymous = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await expect(async () => {
+    const before = await anonymous.get("/api/account/capabilities");
+    const after = await forged.get("/api/account/capabilities");
+    expect(before.status()).toBe(200);
+    expect(remaining(after)).toBeLessThan(remaining(before));
+  }).toPass({ timeout: 10_000 });
+
+  for (const context of [first, bearer, second, forged, anonymous]) await context.dispose();
+});
+
 test("rate limit: session reads do not consume the strict authentication budget", async ({
   playwright,
 }) => {

package/dist/templates/modules/rate-limit/module.manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "rate-limit",
   "manifestVersion": 3,
-  "description": "Provider-neutral Elysia request limiting by authenticated user, validated API key, or trusted-proxy client address.",
+  "description": "Provider-neutral Elysia request limiting by validated API key, signed-in session, or trusted-proxy client address.",
   "requires": ["api-key-auth"],
   "requiresCapabilities": ["cache"],
   "targetApp": "api",
@@ -14,7 +14,7 @@
     "RATE_LIMIT_KEY_PREFIX=podokit:rate-limit",
     "RATE_LIMIT_TTL=60",
     "RATE_LIMIT_MAX=300",
-    "# stricter authentication endpoint ceiling",
+    "# stricter ceiling for authentication writes (admin reads use RATE_LIMIT_MAX)",
     "RATE_LIMIT_AUTH_TTL=60",
     "RATE_LIMIT_AUTH_MAX=20",
     "# higher ceiling for SSR runtime settings and session reads",
@@ -42,7 +42,8 @@
     "Tune the general, authentication, and runtime limits in .env.",
     "Give each deployment that shares Redis a distinct RATE_LIMIT_KEY_PREFIX.",
     "Set RATE_LIMIT_TRUSTED_PROXY_HOPS to the exact number of trusted reverse proxies; keep 0 for direct API access.",
-    "Authenticated users and validated X-API-Key clients receive independent opaque counters; other traffic uses the trusted client address.",
+    "Validated X-API-Key clients and signed-in sessions receive independent opaque counters; other traffic uses the trusted client address.",
+    "Sessions are recognized by verifying the Better Auth cookie or bearer signature with BETTER_AUTH_SECRET, without a database read, so limits apply per session rather than per user.",
     "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Cache failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
     "Register a RateLimitIdentityExtension under RATE_LIMIT_IDENTITY_EXTENSION in app.extensions.ts for another validated machine-key source.",
     "GET /health and GET /health/ready bypass request quotas so orchestrator probes remain reliable.",

package/dist/templates/modules/redis/files/apps/api/src/redis/redis-cache.store.spec.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it, mock } from "bun:test";
+import {
+  FIXED_WINDOW_SCRIPT,
+  FIXED_WINDOW_SCRIPT_SHA,
+  RedisCacheStore,
+} from "./redis-cache.store";
+import { RedisService } from "./redis.service";
+
+const redisUrl = process.env.REDIS_TEST_URL;
+const integrationTest = redisUrl ? it : it.skip;
+
+type Send = (command: string, args: string[]) => Promise<unknown>;
+type SetValue = (key: string, value: string, ...options: Array<string | number>) => Promise<"OK">;
+
+function storeWith(client: { send?: Send; set?: SetValue }): RedisCacheStore {
+  return new RedisCacheStore({ client } as unknown as RedisService);
+}
+
+function redisError(message: string): Error {
+  return Object.assign(new Error(message), { name: "RedisError", code: "ERR_REDIS_SERVER_ERROR" });
+}
+
+describe("RedisCacheStore fixed window", () => {
+  it("runs the cached script by SHA", async () => {
+    const send = mock<Send>(async () => [1, 60_000]);
+    const store = storeWith({ send });
+
+    await expect(
+      store.incrementFixedWindow("counter", { windowMs: 60_000, limit: 5 }),
+    ).resolves.toMatchObject({ allowed: true, count: 1, remaining: 4 });
+    expect(send.mock.calls).toEqual([
+      ["EVALSHA", [FIXED_WINDOW_SCRIPT_SHA, "1", "counter", "60000"]],
+    ]);
+  });
+
+  it("falls back to EVAL when Redis has not cached the script", async () => {
+    const send = mock<Send>(async (command) => {
+      if (command === "EVALSHA") throw redisError("NOSCRIPT No matching script. Please use EVAL.");
+      return [2, 500];
+    });
+    const store = storeWith({ send });
+
+    await expect(
+      store.incrementFixedWindow("counter", { windowMs: 1_000, limit: 1 }),
+    ).resolves.toMatchObject({ allowed: false, count: 2, remaining: 0 });
+    expect(send.mock.calls).toEqual([
+      ["EVALSHA", [FIXED_WINDOW_SCRIPT_SHA, "1", "counter", "1000"]],
+      ["EVAL", [FIXED_WINDOW_SCRIPT, "1", "counter", "1000"]],
+    ]);
+  });
+
+  it("propagates other Redis errors unchanged", async () => {
+    const failure = redisError("LOADING Redis is loading the dataset in memory");
+    const send = mock<Send>(async () => { throw failure; });
+    const store = storeWith({ send });
+
+    await expect(
+      store.incrementFixedWindow("counter", { windowMs: 1_000, limit: 1 }),
+    ).rejects.toBe(failure);
+    expect(send).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("RedisCacheStore set", () => {
+  it("writes the value and its TTL in one command", async () => {
+    const set = mock<SetValue>(async () => "OK");
+    const store = storeWith({ set });
+
+    await store.set("plain", "value");
+    await store.set("expiring", "value", { ttlMs: 1_500 });
+
+    expect(set.mock.calls).toEqual([
+      ["plain", "value"],
+      ["expiring", "value", "PX", 1_500],
+    ]);
+  });
+
+  it("rejects an invalid TTL before writing", async () => {
+    const set = mock<SetValue>(async () => "OK");
+    const store = storeWith({ set });
+
+    await expect(store.set("key", "value", { ttlMs: 0 })).rejects.toThrow("ttlMs");
+    expect(set).not.toHaveBeenCalled();
+  });
+});
+
+describe("RedisCacheStore integration", () => {
+  integrationTest("matches the Redis script SHA and counts atomically", async () => {
+    const previousUrl = process.env.REDIS_URL;
+    process.env.REDIS_URL = redisUrl;
+    const service = new RedisService();
+    const store = new RedisCacheStore(service);
+    const prefix = `podokit:test:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+
+    try {
+      await service.connect();
+      await expect(
+        service.client.send("SCRIPT", ["LOAD", FIXED_WINDOW_SCRIPT]),
+      ).resolves.toBe(FIXED_WINDOW_SCRIPT_SHA);
+
+      const counter = `${prefix}:counter`;
+      const options = { windowMs: 60_000, limit: 1 };
+      await expect(store.incrementFixedWindow(counter, options)).resolves.toMatchObject({
+        allowed: true,
+        count: 1,
+      });
+      await expect(store.incrementFixedWindow(counter, options)).resolves.toMatchObject({
+        allowed: false,
+        count: 2,
+      });
+
+      const expiring = `${prefix}:expiring`;
+      await store.set(expiring, "value", { ttlMs: 60_000 });
+      await expect(store.get(expiring)).resolves.toBe("value");
+      expect(await service.client.pttl(expiring)).toBeGreaterThan(0);
+
+      await service.del(counter);
+      await service.del(expiring);
+    } finally {
+      service.close();
+      if (previousUrl === undefined) delete process.env.REDIS_URL;
+      else process.env.REDIS_URL = previousUrl;
+    }
+  });
+});

package/dist/templates/modules/redis/files/apps/api/src/redis/redis-cache.store.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { RedisClient } from "bun";
 import type {
   CacheSetOptions,
@@ -7,13 +8,19 @@ import type {
 } from "@podosoft/podokit-runtime";
 import type { RedisService } from "./redis.service";
 
-const FIXED_WINDOW_SCRIPT = `
+export const FIXED_WINDOW_SCRIPT = `
 local count = redis.call('INCR', KEYS[1])
 if count == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
 local ttl = redis.call('PTTL', KEYS[1])
 return { count, ttl }
 `;
 
+export const FIXED_WINDOW_SCRIPT_SHA = createHash("sha1").update(FIXED_WINDOW_SCRIPT).digest("hex");
+
+function isMissingScript(error: unknown): boolean {
+  return error instanceof Error && error.message.startsWith("NOSCRIPT");
+}
+
 function resultNumber(value: unknown): number | undefined {
   if (typeof value === "number") return value;
   if (typeof value === "string") {
@@ -35,13 +42,14 @@ export class RedisCacheStore implements CacheStore {
   }
 
   async set(key: string, value: string, options: CacheSetOptions = {}): Promise<void> {
-    await this.client.set(key, value);
-    if (options.ttlMs !== undefined) {
-      if (!Number.isSafeInteger(options.ttlMs) || options.ttlMs < 1) {
-        throw new Error("ttlMs must be a positive integer");
-      }
-      await this.client.send("PEXPIRE", [key, String(options.ttlMs)]);
+    if (options.ttlMs === undefined) {
+      await this.client.set(key, value);
+      return;
+    }
+    if (!Number.isSafeInteger(options.ttlMs) || options.ttlMs < 1) {
+      throw new Error("ttlMs must be a positive integer");
     }
+    await this.client.set(key, value, "PX", options.ttlMs);
   }
 
   async delete(key: string): Promise<boolean> {
@@ -58,12 +66,7 @@ export class RedisCacheStore implements CacheStore {
     if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
       throw new Error("limit must be a positive integer");
     }
-    const result = await this.client.send("EVAL", [
-      FIXED_WINDOW_SCRIPT,
-      "1",
-      key,
-      String(options.windowMs),
-    ]);
+    const result = await this.runFixedWindow(key, options.windowMs);
     if (!Array.isArray(result)) throw new Error("Redis returned an invalid cache counter");
     const count = resultNumber(result[0]);
     const ttlMs = resultNumber(result[1]);
@@ -78,5 +81,16 @@ export class RedisCacheStore implements CacheStore {
     };
   }
 
+  private async runFixedWindow(key: string, windowMs: number): Promise<unknown> {
+    const args = ["1", key, String(windowMs)];
+    try {
+      return await this.client.send("EVALSHA", [FIXED_WINDOW_SCRIPT_SHA, ...args]);
+    } catch (error) {
+      // Redis forgets scripts on restart, failover, or SCRIPT FLUSH; EVAL reloads it.
+      if (!isMissingScript(error)) throw error;
+      return this.client.send("EVAL", [FIXED_WINDOW_SCRIPT, ...args]);
+    }
+  }
+
   close(): void {}
 }

package/dist/templates/modules/sse/files/apps/api/src/events/event-envelope.ts

@@ -0,0 +1,123 @@
+/** Every listed field must match. Within a list, any entry matches. */
+export interface EventAudience {
+  userIds?: string[];
+  roles?: string[];
+  organizationId?: string;
+}
+
+export interface EventEnvelope<T = unknown> {
+  topic: string;
+  /** Omit to deliver to every stream subscribed to the topic. */
+  audience?: EventAudience;
+  data: T;
+  /** Sent as the SSE `id:`. Defaults to a per-connection sequence number. */
+  id?: string;
+}
+
+/** The identity a stream was opened with, resolved once at connect. */
+export interface EventSubscriber {
+  userId: string;
+  roles: readonly string[];
+  organizationId?: string;
+}
+
+/** Topics and event ids share one charset so they can never break SSE framing. */
+export const EVENT_NAME_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$";
+const EVENT_NAME = new RegExp(EVENT_NAME_PATTERN);
+
+export class InvalidEventError extends TypeError {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidEventError";
+  }
+}
+
+export function isEventName(value: unknown): value is string {
+  return typeof value === "string" && EVENT_NAME.test(value);
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function stringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const items: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string" || item.length === 0) return undefined;
+    items.push(item);
+  }
+  return items;
+}
+
+function readAudience(value: unknown): EventAudience | string {
+  const source = record(value);
+  if (!source) return "audience must be an object";
+  const audience: EventAudience = {};
+  if (source.userIds !== undefined) {
+    const userIds = stringList(source.userIds);
+    if (!userIds) return "audience.userIds must be a list of non-empty strings";
+    audience.userIds = userIds;
+  }
+  if (source.roles !== undefined) {
+    const roles = stringList(source.roles);
+    if (!roles) return "audience.roles must be a list of non-empty strings";
+    audience.roles = roles;
+  }
+  if (source.organizationId !== undefined) {
+    if (typeof source.organizationId !== "string" || source.organizationId.length === 0) {
+      return "audience.organizationId must be a non-empty string";
+    }
+    audience.organizationId = source.organizationId;
+  }
+  // An empty audience is almost always a recipient list that failed to resolve;
+  // treating it as a broadcast would leak the event.
+  if (
+    audience.userIds === undefined &&
+    audience.roles === undefined &&
+    audience.organizationId === undefined
+  ) {
+    return "audience must set userIds, roles, or organizationId";
+  }
+  return audience;
+}
+
+/** Normalizes an envelope, or returns why it is invalid. */
+export function readEnvelope(value: unknown): EventEnvelope | string {
+  const source = record(value);
+  if (!source) return "event must be an object";
+  if (!isEventName(source.topic)) return `topic must match ${EVENT_NAME_PATTERN}`;
+  if (source.id !== undefined && !isEventName(source.id)) {
+    return `id must match ${EVENT_NAME_PATTERN}`;
+  }
+  const envelope: EventEnvelope = { topic: source.topic, data: source.data };
+  if (source.id !== undefined) envelope.id = source.id;
+  if (source.audience !== undefined) {
+    const audience = readAudience(source.audience);
+    if (typeof audience === "string") return audience;
+    envelope.audience = audience;
+  }
+  return envelope;
+}
+
+export function validEnvelope(value: EventEnvelope): EventEnvelope {
+  const envelope = readEnvelope(value);
+  if (typeof envelope === "string") throw new InvalidEventError(`Invalid event: ${envelope}`);
+  return envelope;
+}
+
+export type AudienceMatcher = (subscriber: EventSubscriber) => boolean;
+
+export function audienceMatcher(audience: EventAudience | undefined): AudienceMatcher {
+  if (!audience) return () => true;
+  const userIds = audience.userIds ? new Set(audience.userIds) : undefined;
+  const roles = audience.roles ? new Set(audience.roles) : undefined;
+  const organizationId = audience.organizationId;
+  if (!userIds && !roles && organizationId === undefined) return () => false;
+  return (subscriber) =>
+    (!userIds || userIds.has(subscriber.userId)) &&
+    (!roles || subscriber.roles.some((role) => roles.has(role))) &&
+    (organizationId === undefined || subscriber.organizationId === organizationId);
+}