@cosmicdrift/kumiko-bundled-features 0.165.0 → 2.0.0

package/src/sessions/__tests__/sessions.integration.test.ts

@@ -11,6 +11,7 @@ import {
   resetPiiSubjectKmsForTests,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   setupTestStack,
   type TestStack,
@@ -41,6 +42,7 @@ import { SessionHandlers, SessionQueries } from "../constants";
 import { createSessionsFeature } from "../feature";
 import { userSessionEntity, userSessionTable } from "../schema/user-session";
 import { createSessionCallbacks, type SessionCallbacks } from "../session-callbacks";
+import { SESSION_REVOKED_EVENT_QN, type SessionRevokedPayload } from "../session-revoked-event";
 import { sessionCallbacksFromLateBound } from "../testing";
 import { makeSessionHelpers } from "./test-helpers";
 
@@ -84,6 +86,7 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, tenantEntity);
   await unsafeCreateEntityTable(stack.db, userSessionEntity);
   await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+  await createEventsTable(stack.db);
 });
 
 afterAll(async () => {
@@ -91,7 +94,12 @@ afterAll(async () => {
 });
 
 beforeEach(async () => {
-  await resetTestTables(stack.db, [userTable, tenantMembershipsTable, userSessionTable]);
+  await resetTestTables(stack.db, [
+    userTable,
+    tenantMembershipsTable,
+    userSessionTable,
+    eventsTable,
+  ]);
 });
 
 describe("sessions feature — login → check → revoke → rejected", () => {
@@ -191,6 +199,69 @@ describe("sessions feature — login → check → revoke → rejected", () => {
     expect(preservedRevokedAt?.epochMilliseconds).toBe(originalRevokedAt?.epochMilliseconds);
   });
 
+  // #1559 — store_user_sessions stays a direct-write store (no CRUD
+  // lifecycle events, see feature.ts), but a successful revoke must still
+  // append a lightweight session-revoked event so a cross-instance
+  // consumer (#1560) can react. Asserted directly against kumiko_events —
+  // the response body carries no trace of it.
+  test("revoke appends a session-revoked event carrying the userId + sid", async () => {
+    const { userId } = await h.seedUser("event1@example.com", "pw-long-enough");
+    const { token, sid } = await h.login("event1@example.com", "pw-long-enough");
+
+    const res = await h.authedPost("/api/write", token, {
+      type: SessionHandlers.revoke,
+      payload: { id: sid },
+    });
+    expect(res.status).toBe(200);
+
+    const events = await selectMany(stack.db, eventsTable, { type: SESSION_REVOKED_EVENT_QN });
+    expect(events).toHaveLength(1);
+    const payload = events[0]?.["payload"] as SessionRevokedPayload;
+    expect(payload.userId).toBe(userId);
+    expect(payload.sessionIds).toEqual([sid]);
+  });
+
+  // Negative case: an already-revoked sid must NOT emit a second event —
+  // a spurious invalidation is the failure mode #1559 guards against.
+  test("revoking an already-revoked sid emits no additional event", async () => {
+    await h.seedUser("event2@example.com", "pw-long-enough");
+    const first = await h.login("event2@example.com", "pw-long-enough");
+
+    await h.authedPost("/api/write", first.token, {
+      type: SessionHandlers.revoke,
+      payload: { id: first.sid },
+    });
+
+    const second = await h.login("event2@example.com", "pw-long-enough");
+    const retry = await h.authedPost("/api/write", second.token, {
+      type: SessionHandlers.revoke,
+      payload: { id: first.sid },
+    });
+    expect(retry.status).toBe(422);
+
+    const events = await selectMany(stack.db, eventsTable, { type: SESSION_REVOKED_EVENT_QN });
+    expect(events).toHaveLength(1); // only the first, successful revoke
+  });
+
+  test("revoke-all-others appends one event listing every revoked sid", async () => {
+    const { userId } = await h.seedUser("event3@example.com", "pw-long-enough");
+    const a = await h.login("event3@example.com", "pw-long-enough");
+    const b = await h.login("event3@example.com", "pw-long-enough");
+    const c = await h.login("event3@example.com", "pw-long-enough");
+
+    const res = await h.authedPost("/api/write", b.token, {
+      type: SessionHandlers.revokeAllOthers,
+      payload: {},
+    });
+    expect(res.status).toBe(200);
+
+    const events = await selectMany(stack.db, eventsTable, { type: SESSION_REVOKED_EVENT_QN });
+    expect(events).toHaveLength(1);
+    const payload = events[0]?.["payload"] as SessionRevokedPayload;
+    expect(payload.userId).toBe(userId);
+    expect(new Set(payload.sessionIds)).toEqual(new Set([a.sid, c.sid]));
+  });
+
   test("session:mine only returns live sessions, marks the current one", async () => {
     await h.seedUser("mine@example.com", "pw-long-enough");
     // Three logins = three sessions (think: browser, mobile app, tablet)

package/src/sessions/feature.ts

@@ -24,6 +24,7 @@ import {
   type SessionAllOthersRevoker,
   type SessionMassRevoker,
 } from "./session-callbacks";
+import { SESSION_REVOKED_EVENT_SHORT, sessionRevokedSchema } from "./session-revoked-event";
 
 export type SessionsFeatureOptions = {
   // A successful update on the `user` entity that changes the `passwordHash`
@@ -137,6 +138,17 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
       },
     } satisfies SessionStoreProvider);
 
+    // Custom domain-event for cross-instance access-invalidation (#1559).
+    // r.defineEvent registers the schema so ctx.unsafeAppendEvent (revoke,
+    // revoke-all-others) enforces it at append time. revoke-all-for-user
+    // appends via the low-level append() instead (needs to anchor on
+    // SYSTEM_TENANT_ID — see that handler for why) — append() does NOT
+    // consult the registry, so that callsite parses against
+    // sessionRevokedSchema explicitly, same guarantee via a different path.
+    // No projection: the payload IS the read, consumed directly off the
+    // event-store NOTIFY (#1560).
+    r.defineEvent(SESSION_REVOKED_EVENT_SHORT, sessionRevokedSchema);
+
     const handlers = {
       revoke: r.writeHandler(revokeWrite),
       revokeAllOthers: r.writeHandler(revokeAllOthersWrite),

package/src/sessions/handlers/revoke-all-for-user.write.ts

@@ -1,21 +1,28 @@
 import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { access, defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { append } from "@cosmicdrift/kumiko-framework/event-store";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
 import { userSessionTable } from "../schema/user-session";
+import {
+  SESSION_REVOKED_AGGREGATE_TYPE,
+  SESSION_REVOKED_EVENT_QN,
+  sessionRevokedSchema,
+} from "../session-revoked-event";
 
 // Mass-revoke ALL live sessions for a target user — privileged-only.
-// Used by user-data-rights:restrict-account zur Account-Freeze
-// (DSGVO Art. 18) sowie potenziell anderen ops-flows ("ban user",
-// "compromised account"). Im Gegensatz zu revoke-all-others wird
-// die ggf. aufrufende Session ebenfalls revoked — Caller ist System
-// (cron/operator/cross-feature), nicht der Endnutzer selbst.
+// Used by user-data-rights:restrict-account for account-freeze (DSGVO
+// Art. 18) and potentially other ops flows ("ban user", "compromised
+// account"). Unlike revoke-all-others, the caller's own session (if any)
+// is revoked too — the caller is System (cron/operator/cross-feature),
+// not the end-user themselves.
 //
-// Tenant-scope: das userSession-Schema persistiert tenantId pro Row
-// (User kann mehrere Sessions in mehreren Tenants haben). Wir
-// revoken cross-tenant, weil "Account-Restriction" eine globale
-// User-Aussage ist (Forget-Pfad ist auch global, sieht User-Entity-
-// special-Doc). UPDATE filtert nur auf userId.
+// Tenant-scope: the userSession schema persists tenantId per row (a user
+// can have sessions in multiple tenants). We revoke cross-tenant because
+// "account restriction" is a global user-level statement (the forget path
+// is global too, see the User-Entity special doc). The UPDATE filters
+// only on userId.
 export const revokeAllForUserWrite = defineWriteHandler({
   name: "user-session:revoke-all-for-user",
   schema: z.object({
@@ -23,13 +30,45 @@ export const revokeAllForUserWrite = defineWriteHandler({
   }),
   access: { roles: access.privileged },
   handler: async (event, ctx) => {
-    const updated = await updateMany(
+    const updated = await updateMany<{ id: string }>(
       ctx.db.raw,
       userSessionTable,
       { revokedAt: Temporal.Now.instant() },
       { userId: event.payload.userId, revokedAt: null },
     );
 
+    // Lightweight append alongside the direct-write above (#1559) — see
+    // revoke.write.ts for why this isn't a lifecycle event on
+    // store_user_sessions. Uses the low-level append() (not
+    // ctx.unsafeAppendEvent) because this handler is deliberately
+    // cross-tenant: the privileged caller's own tenantId (what
+    // ctx.unsafeAppendEvent would bind to) has no relationship to the
+    // target user's session tenant(s). Anchored on SYSTEM_TENANT_ID
+    // instead, same as the jobs feature's cross-tenant run-lifecycle
+    // events (job-run-logger.ts) — a fresh aggregate per call, so no
+    // predecessor/version_conflict concerns.
+    //
+    // append() itself does NOT validate against the r.defineEvent-
+    // registered schema (that guarantee only comes from going through
+    // ctx.unsafeAppendEvent's dispatcher path). Mirrors job-run-logger.ts:
+    // parse explicitly before the raw append so a shape drift fails loudly
+    // here instead of landing unvalidated on the events table.
+    if (updated.length > 0) {
+      const payload = sessionRevokedSchema.parse({
+        userId: event.payload.userId,
+        sessionIds: updated.map((row) => row.id),
+      });
+      await append(ctx.db.raw, {
+        aggregateId: generateId(),
+        aggregateType: SESSION_REVOKED_AGGREGATE_TYPE,
+        tenantId: SYSTEM_TENANT_ID,
+        expectedVersion: 0,
+        type: SESSION_REVOKED_EVENT_QN,
+        payload,
+        metadata: { userId: event.user.id },
+      });
+    }
+
     return {
       isSuccess: true as const,
       data: { count: updated.length, userId: event.payload.userId },

package/src/sessions/handlers/revoke-all-others.write.ts

@@ -1,10 +1,12 @@
 import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
 import { SessionErrors } from "../constants";
 import { userSessionTable } from "../schema/user-session";
+import { SESSION_REVOKED_AGGREGATE_TYPE, SESSION_REVOKED_EVENT_QN } from "../session-revoked-event";
 
 // "Sign out everywhere else" — keep the caller's current session, kill all
 // other live sessions for this user. Requires `user.sid` so "keep current"
@@ -25,13 +27,29 @@ export const revokeAllOthersWrite = defineWriteHandler({
       );
     }
 
-    const updated = await updateMany(
+    const updated = await updateMany<{ id: string }>(
       ctx.db,
       userSessionTable,
       { revokedAt: Temporal.Now.instant() },
       { userId: event.user.id, revokedAt: null, id: { ne: keepSid } },
     );
 
+    // Lightweight append alongside the direct-write above (#1559) — see
+    // revoke.write.ts for why this isn't a lifecycle event on
+    // store_user_sessions. Skipped when nothing was revoked (no other
+    // live sessions) — a spurious invalidation would be the failure mode.
+    if (updated.length > 0) {
+      await ctx.unsafeAppendEvent({
+        aggregateId: generateId(),
+        aggregateType: SESSION_REVOKED_AGGREGATE_TYPE,
+        type: SESSION_REVOKED_EVENT_QN,
+        payload: {
+          userId: event.user.id,
+          sessionIds: updated.map((row) => row.id),
+        },
+      });
+    }
+
     return { isSuccess: true, data: { count: updated.length } };
   },
 });

package/src/sessions/handlers/revoke.write.ts

@@ -1,10 +1,12 @@
 import { fetchOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
 import { SessionErrors } from "../constants";
 import { userSessionTable } from "../schema/user-session";
+import { SESSION_REVOKED_AGGREGATE_TYPE, SESSION_REVOKED_EVENT_QN } from "../session-revoked-event";
 
 // Revoke a single session by id (= JWT jti). Three distinguishable outcomes:
 //
@@ -36,6 +38,17 @@ export const revokeWrite = defineWriteHandler({
     );
 
     if (updated.length > 0) {
+      // Lightweight append alongside the direct-write above (#1559) — NOT a
+      // lifecycle event for store_user_sessions (that table stays an
+      // unmanaged direct-write store, see feature.ts). Own aggregate id per
+      // revoke, no predecessor to satisfy, no version_conflict against a
+      // concurrent revoke on a different sid.
+      await ctx.unsafeAppendEvent({
+        aggregateId: generateId(),
+        aggregateType: SESSION_REVOKED_AGGREGATE_TYPE,
+        type: SESSION_REVOKED_EVENT_QN,
+        payload: { userId: event.user.id, sessionIds: [event.payload.id] },
+      });
       return { isSuccess: true, data: { id: event.payload.id } };
     }
 

package/src/sessions/index.ts

@@ -15,3 +15,10 @@ export type {
   SessionMassRevoker,
 } from "./session-callbacks";
 export { createSessionCallbacks } from "./session-callbacks";
+export type { SessionRevokedPayload } from "./session-revoked-event";
+export {
+  SESSION_REVOKED_AGGREGATE_TYPE,
+  SESSION_REVOKED_EVENT_QN,
+  SESSION_REVOKED_EVENT_SHORT,
+  sessionRevokedSchema,
+} from "./session-revoked-event";

package/src/sessions/session-callbacks.ts

@@ -2,18 +2,29 @@ import type {
   AuthSessionStatus,
   SessionChecker,
   SessionCreator,
+  SessionMassRevoker,
   SessionMetadata,
   SessionRevoker,
 } from "@cosmicdrift/kumiko-framework/api";
+
+export type { SessionMassRevoker } from "@cosmicdrift/kumiko-framework/api";
+
 import { fetchOne, insertOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { append } from "@cosmicdrift/kumiko-framework/event-store";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
 import { encryptForDirectWrite } from "../shared";
 import { USER_STATUS, type UserStatus, userTable } from "../user";
 import { DEFAULT_SESSION_EXPIRY_MS } from "./constants";
 import { userSessionEntity, userSessionTable } from "./schema/user-session";
+import {
+  SESSION_REVOKED_AGGREGATE_TYPE,
+  SESSION_REVOKED_EVENT_QN,
+  sessionRevokedSchema,
+} from "./session-revoked-event";
 
 // Locked accounts whose live sessions must be refused. deletionRequested is
 // intentionally absent — it's a reversible grace period and the user needs
@@ -28,11 +39,6 @@ const BLOCKED_STATUSES: ReadonlySet<UserStatus> = new Set([
 // login and every request. The (createdAt/revokedAt/ip/userAgent) columns
 // already are the audit trail — a dispatcher roundtrip buys nothing.
 
-// Mass-revoke for a single user. Used by the password-change hook and
-// "sign out everywhere" flows. Returns the count of rows flipped so a
-// caller can log "revoked N other sessions".
-export type SessionMassRevoker = (userId: string) => Promise<number>;
-
 // "Sign out everywhere else, keep this one" — used both by the user-facing
 // revoke-all-others handler and by other features (auth-mfa) that need the
 // same effect from a raw callback instead of a dispatcher round-trip.
@@ -144,6 +150,31 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
         { revokedAt: Temporal.Now.instant() },
         { userId, revokedAt: null },
       );
+
+      // Lightweight append alongside the direct-write above, same pattern
+      // as revoke.write.ts (#1559) — this callback is the password-change
+      // auto-revoke path (sessions/feature.ts postSave hook) and has no
+      // dispatcher ctx to call unsafeAppendEvent from, so it uses the raw
+      // append() like revoke-all-for-user.write.ts does. Without this, the
+      // access-invalidation consumer (#1560) never hears about a password
+      // change and an already-open SSE stream survives it — the exact
+      // "stale JWT mid-stream" gap this feature exists to close.
+      if (result.length > 0) {
+        const payload = sessionRevokedSchema.parse({
+          userId,
+          sessionIds: result.map((row: { id: string }) => row.id),
+        });
+        await append(db, {
+          aggregateId: generateId(),
+          aggregateType: SESSION_REVOKED_AGGREGATE_TYPE,
+          tenantId: SYSTEM_TENANT_ID,
+          expectedVersion: 0,
+          type: SESSION_REVOKED_EVENT_QN,
+          payload,
+          metadata: { userId },
+        });
+      }
+
       return result.length;
     },
 
@@ -156,6 +187,28 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
           ? { userId, revokedAt: null, id: { ne: currentSid } }
           : { userId, revokedAt: null },
       );
+
+      // Same reasoning as sessionMassRevoker above — this raw callback
+      // (used by auth-mfa and other internal callers, distinct from the
+      // user-facing revoke-all-others.write.ts handler which already
+      // appends this event) needs its own append so callers reached
+      // through here also cut open SSE streams.
+      if (result.length > 0) {
+        const payload = sessionRevokedSchema.parse({
+          userId,
+          sessionIds: result.map((row: { id: string }) => row.id),
+        });
+        await append(db, {
+          aggregateId: generateId(),
+          aggregateType: SESSION_REVOKED_AGGREGATE_TYPE,
+          tenantId: SYSTEM_TENANT_ID,
+          expectedVersion: 0,
+          type: SESSION_REVOKED_EVENT_QN,
+          payload,
+          metadata: { userId },
+        });
+      }
+
       return result.length;
     },
   };

package/src/sessions/session-revoked-event.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+// Lightweight custom event appended alongside the direct-write
+// updateMany() in revoke.write.ts / revoke-all-others.write.ts /
+// revoke-all-for-user.write.ts (#1559). store_user_sessions itself stays
+// an unmanaged direct-write store (see feature.ts) — the row columns are
+// the audit trail, this event is NOT a CRUD/lifecycle event for that
+// table and carries no projection. Its only job is to give cross-instance
+// consumers (access-invalidation, #1560) something to LISTEN for via the
+// existing event-store NOTIFY, keyed by the affected userId.
+//
+// _SHORT/_QN pair mirrors cap-counter's rolling-incremented event:
+//   _SHORT — r.defineEvent(short, schema) in feature.ts, framework prefixes
+//            it to the QN below.
+//   _QN    — ctx.unsafeAppendEvent({ type }) / raw append()'s `type` field.
+export const SESSION_REVOKED_EVENT_SHORT = "session-revoked" as const;
+export const SESSION_REVOKED_EVENT_QN = "sessions:event:session-revoked" as const;
+
+// Own aggregate type, decoupled from userSessionEntity's implicit
+// "user-session" — each revoke action mints a fresh aggregate id (no
+// predecessor to satisfy, no version_conflict against concurrent revokes).
+export const SESSION_REVOKED_AGGREGATE_TYPE = "user-session-revocation" as const;
+
+export const sessionRevokedSchema = z.object({
+  userId: z.string().min(1),
+  sessionIds: z.array(z.uuid()).min(1),
+});
+
+export type SessionRevokedPayload = z.infer<typeof sessionRevokedSchema>;

package/src/shared/__tests__/chunked-entity-migration.test.ts

@@ -98,10 +98,10 @@ describe("runChunkedMigration", () => {
       deadlineAt: Number.POSITIVE_INFINITY,
     });
 
-    // Batch 1 processes "a" and pushes failed to 1; the breaker is only
-    // checked at the TOP of the loop, so batch 2 is fetched (batchesProcessed
-    // becomes 2) before the breaker trips and its row is never touched.
-    expect(result.batchesProcessed).toBe(2);
+    // Batch 1 processes "a" and pushes failed to 1; the breaker is checked
+    // before batchesProcessed is incremented for the next fetched batch, so
+    // "b" is fetched but never touched and doesn't count as processed.
+    expect(result.batchesProcessed).toBe(1);
     expect(result.stoppedReason).toBe("too_many_failures");
   });
 

package/src/shared/chunked-entity-migration.ts

@@ -59,13 +59,13 @@ export async function runChunkedMigration<Row>(
     const batch = await opts.nextBatch();
     if (batch.length === 0) break;
 
-    batchesProcessed++;
-
     if (failed >= opts.maxFailures) {
       stoppedReason = "too_many_failures";
       break;
     }
 
+    batchesProcessed++;
+
     for (const row of batch) {
       if (failed >= opts.maxFailures) {
         stoppedReason = "too_many_failures";

package/src/shared/grace-period.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { withoutAmbientTemporal } from "@cosmicdrift/kumiko-framework/testing";
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import { isWithinGracePeriod } from "./grace-period";
+
+describe("isWithinGracePeriod — kumiko-framework#1525/#1550", () => {
+  test("null gracePeriodEnd → false without ambient Temporal", async () => {
+    await withoutAmbientTemporal(() => {
+      expect(isWithinGracePeriod(null)).toBe(false);
+    });
+  });
+
+  test("future vs past without ambient Temporal", async () => {
+    const future = TemporalPolyfill.Now.instant().add({
+      hours: 1,
+    }) as unknown as Temporal.Instant;
+    const past = TemporalPolyfill.Now.instant().subtract({
+      hours: 1,
+    }) as unknown as Temporal.Instant;
+
+    await withoutAmbientTemporal(() => {
+      expect(isWithinGracePeriod(future)).toBe(true);
+      expect(isWithinGracePeriod(past)).toBe(false);
+    });
+  });
+});

package/src/shared/grace-period.ts

@@ -0,0 +1,20 @@
+/** Shared grace-period check for user-data-rights + tenant-lifecycle cancel flows. */
+
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+
+/**
+ * True when `gracePeriodEnd` is still in the future.
+ * Uses the polyfill Instant API so callers don't depend on `globalThis.Temporal`.
+ */
+export function isWithinGracePeriod(gracePeriodEnd: Temporal.Instant | null): boolean {
+  // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant
+  // at runtime — row types resolve against ambient Temporal; polyfill Instant
+  // is a separate nominal type across the two .d.ts sources.
+  return (
+    gracePeriodEnd != null &&
+    TemporalPolyfill.Instant.compare(
+      gracePeriodEnd as unknown as InstanceType<typeof TemporalPolyfill.Instant>,
+      TemporalPolyfill.Now.instant(),
+    ) > 0
+  );
+}

package/src/shared/index.ts

@@ -8,7 +8,9 @@ export {
 export { decryptStoredPii } from "./decrypt-stored-pii";
 export { encryptForDirectWrite } from "./encrypt-for-direct-write";
 export { entitiesOf } from "./entities-of";
+export { isWithinGracePeriod } from "./grace-period";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
+export { mapWithConcurrency } from "./map-with-concurrency";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";
 export type { SystemQueryFn } from "./system-query";
 export { type BurnResult, burnToken, unburnToken } from "./token-burn-store";

package/src/shared/map-with-concurrency.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import { mapWithConcurrency } from "./map-with-concurrency";
+
+describe("mapWithConcurrency", () => {
+  test("preserves result order regardless of completion order", async () => {
+    const delays = [30, 10, 20, 0];
+    const results = await mapWithConcurrency(delays, 4, async (delay, index) => {
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      return index;
+    });
+    expect(results).toEqual([0, 1, 2, 3]);
+  });
+
+  test("never runs more than `limit` calls concurrently", async () => {
+    let active = 0;
+    let maxActive = 0;
+    const items = Array.from({ length: 12 }, (_, i) => i);
+    await mapWithConcurrency(items, 4, async (item) => {
+      active++;
+      maxActive = Math.max(maxActive, active);
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      active--;
+      return item;
+    });
+    expect(maxActive).toBeLessThanOrEqual(4);
+    expect(maxActive).toBeGreaterThan(1);
+  });
+
+  test("propagates the first rejection", async () => {
+    const items = [1, 2, 3];
+    await expect(
+      mapWithConcurrency(items, 4, async (item) => {
+        if (item === 2) throw new Error("boom");
+        return item;
+      }),
+    ).rejects.toThrow("boom");
+  });
+
+  // Two workers rejecting at different times, under 4-way concurrency —
+  // regression guard for the #1398 hazard (an eagerly-fired, never-awaited
+  // Promise surfacing as an unattributed unhandled rejection). Every
+  // worker promise here is an element of the internal `Promise.all` array,
+  // so both rejections are always handled even though the aggregate
+  // `mapWithConcurrency` call already settled on the first one.
+  test("a second rejection after the first doesn't surface as an unhandled rejection", async () => {
+    const unhandled: unknown[] = [];
+    const onUnhandledRejection = (reason: unknown): void => {
+      unhandled.push(reason);
+    };
+    process.on("unhandledRejection", onUnhandledRejection);
+    try {
+      const items = [1, 2, 3, 4, 5, 6, 7, 8];
+      await expect(
+        mapWithConcurrency(items, 4, async (item) => {
+          if (item === 2) {
+            await new Promise((resolve) => setTimeout(resolve, 5));
+            throw new Error("boom-early");
+          }
+          if (item === 5) {
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            throw new Error("boom-late");
+          }
+          await new Promise((resolve) => setTimeout(resolve, 10));
+          return item;
+        }),
+      ).rejects.toThrow("boom-early");
+      // Give the later-rejecting worker's promise a chance to settle and
+      // for a real unhandled rejection (if any) to fire.
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    } finally {
+      process.off("unhandledRejection", onUnhandledRejection);
+    }
+    expect(unhandled).toEqual([]);
+  });
+
+  test("does not claim new items after the first rejection", async () => {
+    const started: number[] = [];
+    const items = Array.from({ length: 20 }, (_, i) => i);
+    await expect(
+      mapWithConcurrency(items, 2, async (item) => {
+        started.push(item);
+        if (item === 0) throw new Error("boom");
+        // Slow enough that without fail-fast, more workers would drain the list.
+        await new Promise((resolve) => setTimeout(resolve, 30));
+        return item;
+      }),
+    ).rejects.toThrow("boom");
+    // At most `limit` in-flight when the first throw sets `failed`; without
+    // the flag the other worker would keep claiming the rest of the 20.
+    expect(started.length).toBeLessThan(items.length);
+    expect(started.length).toBeLessThanOrEqual(3);
+  });
+
+  test("empty input resolves to an empty array without running the worker", async () => {
+    const results = await mapWithConcurrency<number, number>([], 4, async (item) => item);
+    expect(results).toEqual([]);
+  });
+
+  test("limit larger than item count doesn't over-spawn workers", async () => {
+    const items = [1, 2];
+    const results = await mapWithConcurrency(items, 10, async (item) => item * 2);
+    expect(results).toEqual([2, 4]);
+  });
+});