@podosoft/podokit 1.2.0 → 1.3.0

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.migration.spec.ts

@@ -5,16 +5,24 @@ import { revertLatestSqliteMigration, runSqliteMigrations } from "../database/sq
 import { InitAuditLogs1720300000000 } from "../migrations/1720300000000-InitAuditLogs";
 import { IndexAuditLogFilters1792000000000 } from "../migrations/1792000000000-IndexAuditLogFilters";
 
-function runner(type: "postgres" | "better-sqlite3", queries: string[]): QueryRunner {
+function runner(
+  type: "postgres" | "better-sqlite3",
+  queries: string[],
+  invalidIndexes: string[] = [],
+): QueryRunner {
   return {
     connection: { options: { type } },
-    query: (sql: string): Promise<unknown[]> => {
+    query: (sql: string, parameters: unknown[] = []): Promise<unknown[]> => {
       queries.push(sql);
-      return Promise.resolve([]);
+      const invalid = sql.includes("indisvalid") && invalidIndexes.some((name) => parameters[0] === `"${name}"`);
+      return Promise.resolve(invalid ? [{ invalid: 1 }] : []);
     },
   } as unknown as QueryRunner;
 }
 
+const INVALID_CHECK =
+  "SELECT 1 AS \"invalid\" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid";
+
 const FILTER_INDEXES = [
   "IDX_audit_logs_action_createdAt",
   "IDX_audit_logs_actorEmail_createdAt",
@@ -61,20 +69,41 @@ describe("audit log migration", () => {
 });
 
 describe("audit filter index migration", () => {
-  it("replaces the single-column indexes on PostgreSQL and restores them on revert", async () => {
+  it("builds and drops the PostgreSQL indexes concurrently outside a transaction", async () => {
     const migration = new IndexAuditLogFilters1792000000000();
+    // A transaction block would reject CONCURRENTLY; the runner must use "each".
+    expect(migration.transaction).toBe(false);
     const up: string[] = [];
     await migration.up(runner("postgres", up));
     expect(up).toEqual([
-      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_createdAt_id" ON "audit_logs" ("createdAt", "id")',
-      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
-      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_actorEmail_createdAt" ON "audit_logs" ("actorEmail", "createdAt")',
-      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_targetLabel_createdAt" ON "audit_logs" ("targetLabel", "createdAt")',
-      'DROP INDEX IF EXISTS "IDX_audit_logs_action"',
-      'DROP INDEX IF EXISTS "IDX_audit_logs_createdAt"',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_createdAt_id" ON "audit_logs" ("createdAt", "id")',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_actorEmail_createdAt" ON "audit_logs" ("actorEmail", "createdAt")',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_targetLabel_createdAt" ON "audit_logs" ("targetLabel", "createdAt")',
+      'DROP INDEX CONCURRENTLY IF EXISTS "IDX_audit_logs_action"',
+      'DROP INDEX CONCURRENTLY IF EXISTS "IDX_audit_logs_createdAt"',
     ]);
-    expect(up.join("\n")).not.toContain("CONCURRENTLY");
+  });
+
+  it("rebuilds an invalid index left by an interrupted concurrent build", async () => {
+    const up: string[] = [];
+    await new IndexAuditLogFilters1792000000000().up(
+      runner("postgres", up, ["IDX_audit_logs_action_createdAt"]),
+    );
+    const drop = up.indexOf('DROP INDEX CONCURRENTLY IF EXISTS "IDX_audit_logs_action_createdAt"');
+    expect(drop).toBeGreaterThan(-1);
+    expect(up[drop + 1]).toBe(
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
+    );
+    expect(up.filter((sql) => sql.startsWith("DROP INDEX CONCURRENTLY"))).toHaveLength(3);
+  });
 
+  it("restores the single-column PostgreSQL indexes on revert inside its transaction", async () => {
+    const migration = new IndexAuditLogFilters1792000000000();
     const down: string[] = [];
     await migration.down(runner("postgres", down));
     expect(down).toEqual([
@@ -87,6 +116,19 @@ describe("audit filter index migration", () => {
     ]);
   });
 
+  it("keeps plain index statements on SQLite", async () => {
+    const up: string[] = [];
+    await new IndexAuditLogFilters1792000000000().up(runner("better-sqlite3", up));
+    expect(up).toEqual([
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_createdAt_id" ON "audit_logs" ("createdAt", "id")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_actorEmail_createdAt" ON "audit_logs" ("actorEmail", "createdAt")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_targetLabel_createdAt" ON "audit_logs" ("targetLabel", "createdAt")',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_action"',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_createdAt"',
+    ]);
+  });
+
   it("migrates up and down on SQLite", async () => {
     const database = new Database(":memory:");
     const migrations = [

package/dist/templates/modules/audit-log/files/apps/api/src/migrations/1792000000000-IndexAuditLogFilters.ts

@@ -2,8 +2,8 @@ import type { MigrationInterface, QueryRunner } from "typeorm";
 
 // Indexes for the keyset list: ("createdAt", "id") serves the unfiltered pages and
 // the retention prune, and each filter gets its column followed by "createdAt".
-// IF NOT EXISTS lets an operator build them beforehand with CREATE INDEX
-// CONCURRENTLY on a large PostgreSQL table; migrations run in one transaction.
+// PostgreSQL builds and drops them concurrently so audit writes continue on a
+// large table. IF NOT EXISTS keeps indexes an operator already built.
 const INDEXES: Array<[name: string, columns: string]> = [
   ["IDX_audit_logs_createdAt_id", `"createdAt", "id"`],
   ["IDX_audit_logs_action_createdAt", `"action", "createdAt"`],
@@ -18,14 +18,36 @@ const REPLACED: Array<[name: string, columns: string]> = [
 
 export class IndexAuditLogFilters1792000000000 implements MigrationInterface {
   name = "IndexAuditLogFilters1792000000000";
+  // CONCURRENTLY cannot run inside a transaction block. The runner therefore
+  // uses the "each" transaction mode. SQLite migrations always use one.
+  transaction = false;
 
   async up(queryRunner: QueryRunner): Promise<void> {
+    if (queryRunner.connection.options.type !== "postgres") {
+      for (const [name, columns] of INDEXES) {
+        await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`);
+      }
+      for (const [name] of REPLACED) await queryRunner.query(`DROP INDEX IF EXISTS "${name}"`);
+      return;
+    }
     for (const [name, columns] of INDEXES) {
-      await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`);
+      // An interrupted concurrent build leaves an invalid index that
+      // IF NOT EXISTS would keep, so drop it and build again.
+      const invalid = await queryRunner.query(
+        `SELECT 1 AS "invalid" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid`,
+        [`"${name}"`],
+      ) as unknown[];
+      if (invalid.length > 0) await queryRunner.query(`DROP INDEX CONCURRENTLY IF EXISTS "${name}"`);
+      await queryRunner.query(
+        `CREATE INDEX CONCURRENTLY IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`,
+      );
+    }
+    for (const [name] of REPLACED) {
+      await queryRunner.query(`DROP INDEX CONCURRENTLY IF EXISTS "${name}"`);
     }
-    for (const [name] of REPLACED) await queryRunner.query(`DROP INDEX IF EXISTS "${name}"`);
   }
 
+  // A revert runs inside a transaction, so it uses plain statements.
   async down(queryRunner: QueryRunner): Promise<void> {
     for (const [name, columns] of REPLACED) {
       await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`);

package/dist/templates/modules/auth/files/apps/api/src/auth-config/auth-config.rows.spec.ts

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import type { QueryRunner } from "typeorm";
+import { InitAuthConfig1720500000000 } from "../migrations/1720500000000-InitAuthConfig";
+import { readAuthConfigRow, readAuthConfigRows, writeAuthConfigRow } from "./auth-config.rows";
+
+let open: SQL | undefined;
+
+afterEach(async () => {
+  await open?.close();
+  open = undefined;
+});
+
+async function sqliteDatabase(): Promise<SQL> {
+  const sql = new SQL(":memory:");
+  open = sql;
+  const runner = {
+    connection: { options: { type: "better-sqlite3" } },
+    query: (query: string): Promise<unknown> => sql.unsafe(query),
+  } as unknown as QueryRunner;
+  await new InitAuthConfig1720500000000().up(runner);
+  return sql;
+}
+
+describe("auth config rows on SQLite", () => {
+  it("reads the integer enabled column back as a boolean", async () => {
+    const sql = await sqliteDatabase();
+    await writeAuthConfigRow(sql, "sqlite", { key: "smtp", enabled: true, config: { host: "mail" }, secret: null });
+    await writeAuthConfigRow(sql, "sqlite", { key: "social.github", enabled: false, config: {}, secret: null });
+
+    expect(await readAuthConfigRow(sql, "smtp")).toEqual({
+      key: "smtp",
+      enabled: true,
+      config: JSON.stringify({ host: "mail" }),
+      secret: null,
+    });
+    const rows = await readAuthConfigRows(sql);
+    expect(rows.map((row) => [row.key, row.enabled])).toEqual([
+      ["smtp", true],
+      ["social.github", false],
+    ]);
+    expect(await readAuthConfigRow(sql, "server")).toBeNull();
+  });
+
+  it("keeps a boolean through a read and rewrite", async () => {
+    const sql = await sqliteDatabase();
+    await writeAuthConfigRow(sql, "sqlite", { key: "smtp", enabled: true, config: {}, secret: null });
+    const current = await readAuthConfigRow(sql, "smtp");
+    if (!current) throw new Error("expected the smtp row");
+    await writeAuthConfigRow(sql, "sqlite", { ...current, secret: "sealed" });
+    expect((await readAuthConfigRow(sql, "smtp"))?.enabled).toBe(true);
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth-config/auth-config.rows.ts

@@ -0,0 +1,65 @@
+import type { SQL } from "bun";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { authConfigParam } from "./config-param";
+
+export interface AuthConfigRow {
+  key: string;
+  enabled: boolean;
+  config: unknown;
+  secret: string | null;
+}
+
+function configObject(value: unknown): Record<string, unknown> {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value === "string") {
+    try {
+      return configObject(JSON.parse(value) as unknown);
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+// SQLite stores booleans as 0 or 1.
+interface StoredAuthConfigRow extends Omit<AuthConfigRow, "enabled"> {
+  enabled: boolean | number;
+}
+
+function authConfigRow(row: StoredAuthConfigRow): AuthConfigRow {
+  return { ...row, enabled: row.enabled === true || row.enabled === 1 };
+}
+
+export async function readAuthConfigRows(sql: SQL): Promise<AuthConfigRow[]> {
+  const rows = await sql<StoredAuthConfigRow[]>`
+    SELECT "key", "enabled", "config", "secret" FROM "auth_config"
+  `;
+  return rows.map(authConfigRow);
+}
+
+export async function readAuthConfigRow(sql: SQL, key: string): Promise<AuthConfigRow | null> {
+  const rows = await sql<StoredAuthConfigRow[]>`
+    SELECT "key", "enabled", "config", "secret"
+    FROM "auth_config" WHERE "key" = ${key}
+  `;
+  return rows[0] ? authConfigRow(rows[0]) : null;
+}
+
+export async function writeAuthConfigRow(
+  sql: SQL,
+  provider: DatabaseProviderName,
+  row: AuthConfigRow,
+): Promise<void> {
+  const config = authConfigParam(provider, configObject(row.config));
+  await sql`
+    INSERT INTO "auth_config" ("key", "enabled", "config", "secret", "updatedAt")
+    VALUES (${row.key}, ${row.enabled}, ${config}, ${row.secret}, CURRENT_TIMESTAMP)
+    ON CONFLICT ("key") DO UPDATE SET
+      "enabled" = EXCLUDED."enabled",
+      "config" = EXCLUDED."config",
+      "secret" = EXCLUDED."secret",
+      "updatedAt" = CURRENT_TIMESTAMP
+  `;
+}

package/dist/templates/modules/auth/files/apps/api/src/auth-config/auth-config.service.ts

@@ -12,7 +12,13 @@ import {
 } from "@podosoft/podokit-auth";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { refreshAuthNow } from "../auth/auth-provider";
-import { authConfigParam } from "./config-param";
+import {
+  readAuthConfigRow,
+  readAuthConfigRows,
+  writeAuthConfigRow,
+  type AuthConfigRow,
+} from "./auth-config.rows";
+import { resetSessionExpirations } from "./session-expiry";
 
 export type SocialProviderView = {
   id: string;
@@ -73,13 +79,6 @@ export type AuthConfigUpdate = {
   };
 };
 
-interface AuthConfigRow {
-  key: string;
-  enabled: boolean;
-  config: unknown;
-  secret: string | null;
-}
-
 function object(value: unknown): Record<string, unknown> {
   if (value !== null && typeof value === "object" && !Array.isArray(value)) {
     return value as Record<string, unknown>;
@@ -110,30 +109,15 @@ export class AuthConfigService {
   ) {}
 
   private async rows(): Promise<AuthConfigRow[]> {
-    return this.sql<AuthConfigRow[]>`
-      SELECT "key", "enabled", "config", "secret" FROM "auth_config"
-    `;
+    return readAuthConfigRows(this.sql);
   }
 
   private async row(key: string): Promise<AuthConfigRow | null> {
-    const rows = await this.sql<AuthConfigRow[]>`
-      SELECT "key", "enabled", "config", "secret"
-      FROM "auth_config" WHERE "key" = ${key}
-    `;
-    return rows[0] ?? null;
+    return readAuthConfigRow(this.sql, key);
   }
 
   private async upsert(row: AuthConfigRow): Promise<void> {
-    const config = authConfigParam(this.provider, object(row.config));
-    await this.sql`
-      INSERT INTO "auth_config" ("key", "enabled", "config", "secret", "updatedAt")
-      VALUES (${row.key}, ${row.enabled}, ${config}, ${row.secret}, CURRENT_TIMESTAMP)
-      ON CONFLICT ("key") DO UPDATE SET
-        "enabled" = EXCLUDED."enabled",
-        "config" = EXCLUDED."config",
-        "secret" = EXCLUDED."secret",
-        "updatedAt" = CURRENT_TIMESTAMP
-    `;
+    await writeAuthConfigRow(this.sql, this.provider, row);
   }
 
   async describe(): Promise<AuthConfigView> {
@@ -216,7 +200,12 @@ export class AuthConfigService {
     if (update.server) await this.upsertServer(update.server);
     await refreshAuthNow();
     if (update.server?.sessionIdleTimeoutMinutes !== undefined) {
-      await this.resetSessionExpirations(update.server.sessionIdleTimeoutMinutes);
+      const minutes = update.server.sessionIdleTimeoutMinutes;
+      await resetSessionExpirations(
+        this.sql,
+        this.provider,
+        minutes === null ? DEFAULT_SESSION_LIFETIME_SECONDS : minutes * 60,
+      );
     }
     return this.describe();
   }
@@ -285,14 +274,4 @@ export class AuthConfigService {
     }
     await this.upsert({ ...current, config });
   }
-
-  private async resetSessionExpirations(minutes: number | null): Promise<void> {
-    const lifetimeSeconds = minutes === null ? DEFAULT_SESSION_LIFETIME_SECONDS : minutes * 60;
-    await this.sql`
-      UPDATE "session"
-      SET "expiresAt" = CURRENT_TIMESTAMP + (${lifetimeSeconds} * INTERVAL '1 second'),
-          "updatedAt" = CURRENT_TIMESTAMP
-      WHERE "expiresAt" > CURRENT_TIMESTAMP
-    `;
-  }
 }

package/dist/templates/modules/auth/files/apps/api/src/auth-config/session-expiry.spec.ts

@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import { resetSessionExpirations } from "./session-expiry";
+
+let open: SQL | undefined;
+
+afterEach(async () => {
+  await open?.close();
+  open = undefined;
+});
+
+describe("session expiry reset on SQLite", () => {
+  it("moves active sessions to the new lifetime and leaves expired ones", async () => {
+    const sql = new SQL(":memory:");
+    open = sql;
+    // Better Auth stores SQLite dates as ISO 8601 text.
+    await sql`CREATE TABLE "session" ("id" text PRIMARY KEY, "expiresAt" date NOT NULL, "updatedAt" date NOT NULL)`;
+    const now = new Date("2026-10-15T10:00:00.000Z");
+    const active = new Date(now.getTime() + 3_600_000).toISOString();
+    const expired = new Date(now.getTime() - 1_000).toISOString();
+    await sql`INSERT INTO "session" VALUES (${"active"}, ${active}, ${active}), (${"expired"}, ${expired}, ${expired})`;
+
+    await resetSessionExpirations(sql, "sqlite", 1_800, now);
+
+    const rows = await sql<Array<{ id: string; expiresAt: string; updatedAt: string }>>`
+      SELECT "id", "expiresAt", "updatedAt" FROM "session" ORDER BY "id"
+    `;
+    expect(rows).toEqual([
+      { id: "active", expiresAt: "2026-10-15T10:30:00.000Z", updatedAt: now.toISOString() },
+      { id: "expired", expiresAt: expired, updatedAt: expired },
+    ]);
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth-config/session-expiry.ts

@@ -0,0 +1,29 @@
+import type { SQL } from "bun";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+
+/** Give every active session the configured lifetime from now. */
+export async function resetSessionExpirations(
+  sql: SQL,
+  provider: DatabaseProviderName,
+  lifetimeSeconds: number,
+  now: Date = new Date(),
+): Promise<void> {
+  if (provider === "sqlite") {
+    // Better Auth stores SQLite dates as ISO 8601 text, which sorts in time
+    // order. SQLite has no interval arithmetic.
+    const current = now.toISOString();
+    const expiresAt = new Date(now.getTime() + lifetimeSeconds * 1000).toISOString();
+    await sql`
+      UPDATE "session"
+      SET "expiresAt" = ${expiresAt}, "updatedAt" = ${current}
+      WHERE "expiresAt" > ${current}
+    `;
+    return;
+  }
+  await sql`
+    UPDATE "session"
+    SET "expiresAt" = CURRENT_TIMESTAMP + (${lifetimeSeconds} * INTERVAL '1 second'),
+        "updatedAt" = CURRENT_TIMESTAMP
+    WHERE "expiresAt" > CURRENT_TIMESTAMP
+  `;
+}

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/bootstrap-admin.md

@@ -1,6 +1,8 @@
 # Bootstrap the initial administrator
 
 Use the generated database-backed command after the API build and migrations.
+With `NODE_ENV=production` it loads the bundled `dist/bootstrap-admin-runtime.js`;
+otherwise it runs the source entry. It supports PostgreSQL and SQLite.
 Do not create the first administrator through the public sign-up page.
 
 ## Set the persistent allowlist

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

@@ -105,8 +105,8 @@ 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.
+    // Admin reads need an admin session and are not credential attempts. The
+    // dashboard and organizations pages read users through Better Auth.
     if (method === "GET" && path.startsWith("/api/auth/admin/")) {
       return { name: "general", ttlSeconds: this.config.ttlSeconds, limit: this.config.limit };
     }

package/dist/templates/modules/sse/files/apps/api/src/events/events.module.spec.ts

@@ -4,7 +4,12 @@ import { MemoryEventBus } from "@podosoft/podokit-runtime";
 import { Elysia } from "elysia";
 import type { RequestIdentity } from "../core/services";
 import { ReadinessService } from "../health/readiness.service";
-import { eventsRoutes, requestEventIdentity, type EventIdentity } from "./events.module";
+import {
+  eventsRoutes,
+  maxStreamsPerUser,
+  requestEventIdentity,
+  type EventIdentity,
+} from "./events.module";
 import { EventsService } from "./events.service";
 
 /** Maps the `x-user`, `x-admin`, `x-roles`, and `x-org` test headers to the request identity. */
@@ -201,3 +206,45 @@ describe("default event identity", () => {
     expect(await identity.subscriber(new Request("http://localhost/events/stream"))).toBeUndefined();
   });
 });
+
+describe("stream limit configuration", () => {
+  it("reads SSE_MAX_STREAMS_PER_USER and defaults to eight", () => {
+    expect(maxStreamsPerUser({})).toBe(8);
+    expect(maxStreamsPerUser({ SSE_MAX_STREAMS_PER_USER: "3" })).toBe(3);
+    for (const value of ["0", "-1", "1.5", "many"]) {
+      expect(() => maxStreamsPerUser({ SSE_MAX_STREAMS_PER_USER: value })).toThrow(
+        "SSE_MAX_STREAMS_PER_USER must be a positive integer",
+      );
+    }
+  });
+
+  it("answers 429 EVENTS_STREAM_LIMIT over HTTP", async () => {
+    const events = new EventsService(new MemoryEventBus(), new ReadinessService(), {
+      maxStreamsPerUser: 1,
+    });
+    await events.connect();
+    const controllers: AbortController[] = [];
+    opened.push({ events, controllers });
+    const app = new Elysia()
+      .onError(({ error, set }) => {
+        if (!(error instanceof AppException)) return undefined;
+        set.status = error.statusCode;
+        return { code: error.code };
+      })
+      .use(eventsRoutes(events, headerIdentity));
+    const send = (): Promise<Response> => {
+      const controller = new AbortController();
+      controllers.push(controller);
+      return app.handle(
+        new Request("http://localhost/events/stream", {
+          headers: { "x-user": "u1" },
+          signal: controller.signal,
+        }),
+      );
+    };
+    expect((await send()).status).toBe(200);
+    const refused = await send();
+    expect(refused.status).toBe(429);
+    expect(await refused.json()).toEqual({ code: "EVENTS_STREAM_LIMIT" });
+  });
+});

package/dist/templates/modules/sse/files/apps/api/src/events/events.module.ts

@@ -22,6 +22,15 @@ import { EventsService } from "./events.service";
 
 export const SSE_EVENTS = Symbol("sse-events") as ServiceKey<EventsService>;
 
+/** `SSE_MAX_STREAMS_PER_USER`: open streams one user may hold on each API replica. */
+export function maxStreamsPerUser(env: Record<string, string | undefined> = process.env): number {
+  const value = Number(env.SSE_MAX_STREAMS_PER_USER ?? 8);
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error("SSE_MAX_STREAMS_PER_USER must be a positive integer");
+  }
+  return value;
+}
+
 /** Resolves who opens a stream. Register one in app.extensions.ts to replace the default. */
 export interface EventIdentity {
   subscriber(request: Request): Promise<EventSubscriber | undefined>;
@@ -84,7 +93,9 @@ export function eventsRoutes(
           "Signed-in users only. `topics` is a comma-separated list; without it the stream " +
           "carries every topic that has no authorizer. Each data event is a default " +
           "`message` whose data is `{ topic, data }`. A `resync` event means events were " +
-          "dropped and the client should reload its state.",
+          "dropped and the client should reload its state. A user may hold " +
+          "`SSE_MAX_STREAMS_PER_USER` streams (default 8) on each API replica; another " +
+          "answers 429 `EVENTS_STREAM_LIMIT`.",
       },
     })
     .post("/events", async ({ request, body, set }) => {
@@ -132,7 +143,9 @@ const eventsPlugin: AppPlugin = ({ services }) =>
 export const eventsModule: PodokitModule = {
   name: "sse",
   configure: (_env, services): void => {
-    const events = new EventsService(services.resolve(EVENTS), services.resolve(READINESS));
+    const events = new EventsService(services.resolve(EVENTS), services.resolve(READINESS), {
+      maxStreamsPerUser: maxStreamsPerUser(),
+    });
     services.register(SSE_EVENTS, events, () => events.close());
     services.onStart(() => events.connect());
   },

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.spec.ts

@@ -353,6 +353,41 @@ describe("per-connection safety", () => {
   });
 });
 
+describe("per-user stream limit", () => {
+  it("refuses a user's stream beyond the limit on this replica and frees slots on close", async () => {
+    const events = await service({ maxStreamsPerUser: 2 });
+    const first = await open(events, user("a"));
+    await open(events, user("a"));
+
+    const refused = await open(events, user("a")).catch((error: unknown) => error);
+    expect(refused).toBeInstanceOf(AppException);
+    expect((refused as AppException).code).toBe("EVENTS_STREAM_LIMIT");
+    expect((refused as AppException).statusCode).toBe(429);
+    expect(events.streamCount).toBe(2);
+
+    // Other users keep their own allowance.
+    await open(events, user("b"));
+    first.close();
+    await open(events, user("a"));
+    expect(events.streamCount).toBe(3);
+  });
+
+  it("counts only live streams after a client disconnects", async () => {
+    const events = await service({ maxStreamsPerUser: 1 });
+    const controller = new AbortController();
+    await events.open(user("a"), undefined, controller.signal);
+    controller.abort();
+    await open(events, user("a"));
+    expect(events.streamCount).toBe(1);
+  });
+
+  it("allows eight streams per user by default", async () => {
+    const events = await service();
+    for (let index = 0; index < 8; index += 1) await open(events, user("a"));
+    await expect(open(events, user("a"))).rejects.toThrow("Too many open event streams");
+  });
+});
+
 describe("SSE wire format", () => {
   it("encodes data events as default messages and control frames separately", () => {
     expect(encodeFrame({ kind: "event", id: "7", data: '{"topic":"t","data":1}' })).toBe(

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.ts

@@ -27,6 +27,8 @@ export interface EventsServiceOptions {
   retryMs?: number;
   /** Streams end after this long so clients reconnect with a fresh identity. */
   maxConnectionMs?: number;
+  /** Open streams one user may hold on this replica. */
+  maxStreamsPerUser?: number;
   scheduler?: Scheduler;
   now?: () => number;
 }
@@ -35,7 +37,9 @@ export class EventsService {
   readonly topics = new TopicAuthorizers();
   readonly retryMs: number;
   private readonly streamOptions: EventStreamOptions;
+  private readonly maxStreamsPerUser: number;
   private readonly streams = new Set<EventStream>();
+  private readonly byUser = new Map<string, Set<EventStream>>();
   private readonly byTopic = new Map<string, Set<EventStream>>();
   private readonly everyTopic = new Set<EventStream>();
   private unregisterReadiness?: () => void;
@@ -47,6 +51,7 @@ export class EventsService {
     options: EventsServiceOptions = {},
   ) {
     this.retryMs = options.retryMs ?? 3_000;
+    this.maxStreamsPerUser = options.maxStreamsPerUser ?? 8;
     this.streamOptions = {
       queueLimit: options.queueLimit ?? 256,
       heartbeatMs: options.heartbeatMs ?? 5_000,
@@ -93,7 +98,9 @@ export class EventsService {
 
   /**
    * Opens a stream for `subscriber`. Without `topics` the stream receives every
-   * topic that has no authorizer; guarded topics must be requested by name.
+   * topic that has no authorizer; guarded topics must be requested by name. A
+   * user beyond the per-user limit is refused rather than closing an older
+   * stream, which would make that client reconnect and refuse the next one.
    */
   async open(
     subscriber: EventSubscriber,
@@ -109,6 +116,10 @@ export class EventsService {
         );
       }
     }
+    // No await between this check and attach(), so concurrent opens cannot pass it together.
+    if ((this.byUser.get(subscriber.userId)?.size ?? 0) >= this.maxStreamsPerUser) {
+      throw new AppException("EVENTS_STREAM_LIMIT", "Too many open event streams", 429);
+    }
     const stream = new EventStream(
       subscriber,
       topics ? new Set(topics) : undefined,
@@ -142,6 +153,9 @@ export class EventsService {
 
   private attach(stream: EventStream): void {
     this.streams.add(stream);
+    const held = this.byUser.get(stream.subscriber.userId) ?? new Set<EventStream>();
+    held.add(stream);
+    this.byUser.set(stream.subscriber.userId, held);
     if (!stream.topics) {
       this.everyTopic.add(stream);
       return;
@@ -155,6 +169,9 @@ export class EventsService {
 
   private detach(stream: EventStream): void {
     this.streams.delete(stream);
+    const held = this.byUser.get(stream.subscriber.userId);
+    held?.delete(stream);
+    if (held?.size === 0) this.byUser.delete(stream.subscriber.userId);
     if (!stream.topics) {
       this.everyTopic.delete(stream);
       return;