@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/sessions/feature.ts

@@ -0,0 +1,240 @@
+import {
+  EXT_SESSION_STORE,
+  type SessionStore,
+  type SessionStoreProvider,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { type DbConnection, deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { USER_SESSION_ENTITY_NAME } from "./constants.js";
+import { cleanupJob } from "./handlers/cleanup.job.js";
+import { detailQuery } from "./handlers/detail.query.js";
+import { listQuery } from "./handlers/list.query.js";
+import { mineQuery } from "./handlers/mine.query.js";
+import { revokeWrite } from "./handlers/revoke.write.js";
+import { revokeAllForUserWrite } from "./handlers/revoke-all-for-user.write.js";
+import { revokeAllOthersWrite } from "./handlers/revoke-all-others.write.js";
+import { SESSIONS_I18N } from "./i18n.js";
+import { userSessionEntity } from "./schema/user-session.js";
+import { sessionDetailScreen, sessionListScreen, sessionMineScreen } from "./screens.js";
+import {
+  createSessionCallbacks,
+  type SessionAllOthersRevoker,
+  type SessionMassRevoker,
+} from "./session-callbacks.js";
+import { SESSION_REVOKED_EVENT_SHORT, sessionRevokedSchema } from "./session-revoked-event.js";
+
+const CLEANUP_ESCAPE_HATCH_REASON = "deletes expired session rows of every tenant";
+
+export type SessionsFeatureOptions = {
+  // A successful update on the `user` entity that changes `passwordHash`
+  // triggers a mass-revoke of every live session for that user.
+  // Industry-standard "password-change signs you out everywhere" flow,
+  // including the session that did the change itself — the client has
+  // to re-login after a password change.
+  //
+  // Runs as an afterCommit postSave hook: the password-change commits first,
+  // then the sessions are revoked. Best-effort — if the mass-revoker throws,
+  // the password change is NOT rolled back (a password change with a stale
+  // session still wins over a user-visible error on the change itself).
+  //
+  // Default: run{Prod,Dev}App bind their own sessionMassRevoker via
+  // `bindAutoRevokeOnPasswordChange` (secure-by-default). Set this option
+  // only to supply a custom revoker — an explicit value wins over the
+  // runtime binding.
+  readonly autoRevokeOnPasswordChange?: SessionMassRevoker;
+  // Session JWT / store_user_sessions TTL. Was previously auth.sessions.expiresInMs
+  // (#1372) — lives on the sessions feature now that sessionStore is the wiring.
+  readonly expiresInMs?: number;
+};
+
+export type BindAutoRevokeOnPasswordChange = (revoker: SessionMassRevoker) => void;
+export type BindRevokeAllOtherSessions = (revoker: SessionAllOthersRevoker) => void;
+
+// Reads the late-bind setter off a mounted sessions feature's exports.
+// run{Prod,Dev}App call it once the DB connection is concrete — the feature
+// itself is constructed in app run-config long before a db exists, so the
+// revoker can't be a constructor argument.
+export function bindAutoRevokeFromFeature(
+  feature: FeatureDefinition,
+): BindAutoRevokeOnPasswordChange | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "bindAutoRevokeOnPasswordChange" in exports) {
+    const { bindAutoRevokeOnPasswordChange } = exports as {
+      bindAutoRevokeOnPasswordChange: unknown;
+    };
+    if (typeof bindAutoRevokeOnPasswordChange === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return bindAutoRevokeOnPasswordChange as BindAutoRevokeOnPasswordChange;
+    }
+  }
+  return undefined;
+}
+
+// The sessions feature registers the store_user_sessions table (as an
+// unmanaged direct-write store, NOT an r.entity — see below) and the three
+// user-facing handlers (mine/revoke/revoke-all-others). It intentionally does NOT
+// export a sessionCreator/sessionRevoker here — those are produced by
+// `createSessionCallbacks()` at app-setup time and wired into
+// `buildServer({ auth: { ... } })`.
+//
+// Why the split: handlers participate in the dispatcher pipeline (access
+// checks, audit, hooks). The creator/revoker callbacks run on the hot
+// login/request path and do direct-DB writes — threading them through the
+// dispatcher would buy latency without added safety (the row columns ARE
+// the audit trail).
+//
+// Not system-scoped: sessions live per tenant, and the handlers should only
+// see rows in the caller's active tenant.
+export function createSessionsFeature(options?: SessionsFeatureOptions): FeatureDefinition {
+  return defineFeature(
+    "sessions",
+    (r) => {
+      r.describe(
+        "Tracks signed-in clients in the `store_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the same callbacks are also registered as an auth-foundation sessionStore provider, resolvable generically via `resolveSessionStore()`. The feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
+      );
+      r.uiHints({
+        displayLabel: "Sessions · Server-side Logout",
+        category: "identity",
+        recommended: false,
+      });
+      // sessionChecker reads read_users on every authenticated request (status
+      // gate for locked accounts) — make that a boot-time dependency so a
+      // sessions-without-user wiring fails validateBoot instead of 500ing live.
+      // auth-foundation owns EXT_SESSION_STORE, which the useExtension below
+      // registers against.
+      r.requires("user", "auth-foundation");
+      // store_user_sessions is a hot-path direct-write store: sessionCreator
+      // inserts and the revoke handlers update rows WITHOUT emitting lifecycle
+      // events (the row columns ARE the audit trail). Registering it as
+      // r.entity would make it a rebuildable implicit projection whose replay
+      // finds zero session events and swaps an empty shadow over the live
+      // table — wiping every active session on the next projection rebuild
+      // (#498/#494). r.storeTable keeps the migration DDL but opts the
+      // table out of implicit rebuild, like jobs/channel-in-app/feature-toggles
+      // which are direct-write stores too.
+      r.storeTable(
+        deriveEntityTableMeta(USER_SESSION_ENTITY_NAME, userSessionEntity, { source: "unmanaged" }),
+        {
+          reason: "read_side.user_sessions_direct_write",
+          // sessionCreator encrypts ip/userAgent via encryptForDirectWrite (#820).
+          piiEncryptedOnWrite: true,
+        },
+      );
+
+      // Self-registers as auth-foundation's sessionStore provider (#1371) —
+      // wraps the same createSessionCallbacks() used by the manual
+      // buildServer({ auth: { ... } }) wiring above; a future issue (#1372)
+      // removes that manual wiring once the middleware resolves generically
+      // via resolveSessionStore().
+      r.useExtension(EXT_SESSION_STORE, "default", {
+        build: (deps): SessionStore => {
+          const callbacks = createSessionCallbacks({
+            db: deps.db,
+            ...(options?.expiresInMs !== undefined && { expiresInMs: options.expiresInMs }),
+          });
+          return {
+            creator: callbacks.sessionCreator,
+            revoker: callbacks.sessionRevoker,
+            checker: callbacks.sessionChecker,
+            massRevoker: callbacks.sessionMassRevoker,
+            revokeAllOthers: callbacks.sessionRevokeAllOthers,
+          };
+        },
+      } 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, { piiFields: "none" });
+
+      const handlers = {
+        revoke: r.writeHandler(revokeWrite),
+        revokeAllOthers: r.writeHandler(revokeAllOthersWrite),
+        revokeAllForUser: r.writeHandler(revokeAllForUserWrite),
+      };
+      r.exposesApi("sessions.revokeAllForUser");
+
+      const queries = {
+        mine: r.queryHandler(mineQuery),
+        list: r.queryHandler(listQuery),
+        detail: r.queryHandler(detailQuery),
+      };
+
+      // Retention: chunked DELETE of expired/revoked rows. Manual trigger
+      // only so dev environments don't churn. Ops wires a cron in the app's
+      // dispatcher config when running a long-lived deployment.
+      r.job({
+        name: "cleanup",
+        trigger: { manual: true },
+        escapeHatch: { reason: CLEANUP_ESCAPE_HATCH_REASON },
+        handler: (payload, ctx) =>
+          cleanupJob(
+            payload,
+            ctx,
+            ctx.db.unsafeRaw(CLEANUP_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+          ),
+      });
+
+      // Cross-feature entity hook on "user". `r.entityHook` (NOT `r.hook`) is
+      // the supported cross-feature path: entity-keyed, not prefixed by the
+      // registering feature. Fires after every successful write on any
+      // user-entity handler; we only act when one of REVOKE_TRIGGERING_FIELDS
+      // is part of the changes-delta the handler was given.
+      //
+      // Checking `changes[field] !== undefined` is cheaper and more correct
+      // than diffing data vs previous — "undefined in changes" means "the
+      // handler didn't touch this column", which is exactly the signal we
+      // want to skip on. Works for both direct user:update calls and any
+      // other handler that happens to write the column.
+      //
+      // Only `passwordHash` here: `status` changes go through
+      // updateUserLifecycle(), which writes via the event-store executor
+      // directly and never runs this postSave hook. restrict-account.write.ts
+      // already revokes sessions explicitly for that transition, and
+      // sessionChecker blocks a status-locked principal on its next request
+      // regardless.
+      const REVOKE_TRIGGERING_FIELDS = ["passwordHash"] as const;
+      let autoRevoke = options?.autoRevokeOnPasswordChange;
+      r.hook("postSave", { allOf: "user" }, async (ctx) => {
+        // skip: nothing bound — stateless-JWT deployments without a runtime
+        // that calls bindAutoRevokeOnPasswordChange keep the old behavior.
+        if (!autoRevoke) return;
+        // skip: brand-new user, no sessions can possibly exist yet. The
+        // initial passwordHash on a user:create would trip the second guard
+        // otherwise — every registration would do a mass-revoke roundtrip
+        // for a user who literally has no rows in user_sessions.
+        if (ctx.isNew) return;
+        // skip: handler didn't touch any revoke-triggering field
+        if (!REVOKE_TRIGGERING_FIELDS.some((field) => ctx.changes[field] !== undefined)) return;
+        await autoRevoke(String(ctx.id));
+      });
+
+      const bindAutoRevokeOnPasswordChange: BindAutoRevokeOnPasswordChange = (revoker) => {
+        // explicit constructor option wins over the runtime binding
+        autoRevoke ??= revoker;
+      };
+
+      r.translations({ keys: SESSIONS_I18N });
+
+      r.screen(sessionListScreen);
+      r.screen(sessionDetailScreen);
+      r.screen(sessionMineScreen);
+      r.nav({
+        id: "session-list",
+        label: "sessions:nav.sessionList",
+        icon: "list",
+        screen: "sessions:screen:session-list",
+        order: 10,
+      });
+
+      return { handlers, queries, bindAutoRevokeOnPasswordChange };
+    },
+    { dedupeOptions: options ?? {} },
+  );
+}

package/packages/bundled-features/src/sessions/handlers/cleanup.job.ts

@@ -0,0 +1,83 @@
+// Retention/cleanup job for user_sessions. Without this the table grows
+// monotonically: every login adds one row, logout only flips revokedAt. A
+// long-lived app would eventually accumulate millions of dead rows that
+// slow the sessionChecker point-read down and bloat backups.
+//
+// Policy:
+//   - Delete rows whose expiresAt is older than `olderThanDays` (default
+//     30d). Expired sessions can never go live again; the audit trail
+//     isn't useful past the retention window.
+//   - Delete rows whose revokedAt is older than `olderThanDays`. Same
+//     reasoning: a session revoked months ago has no operational value.
+//   - NEVER delete currently-live rows. Safe by construction — the WHERE
+//     clause requires either expiresAt OR revokedAt to be past-cutoff.
+//
+// Chunked DELETE (default 1000/batch) keeps lock durations bounded. Ops
+// schedules this daily (manual trigger by default — opt-in to cron in the
+// app's feature-wiring so a dev environment doesn't churn through a fresh
+// seed). Mirror of secrets/retention.job in shape.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { JobContext } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { deleteStaleSessionsBatch } from "../db/queries/cleanup.js";
+
+const DEFAULT_OLDER_THAN_DAYS = 30;
+const DEFAULT_BATCH_SIZE = 1000;
+
+export type SessionCleanupPayload = {
+  readonly olderThanDays?: number;
+  readonly batchSize?: number;
+  readonly maxDurationMs?: number;
+};
+
+export type SessionCleanupResult = {
+  readonly deleted: number;
+  readonly batchesProcessed: number;
+  readonly stoppedReason: "empty" | "timeout" | "signal";
+};
+
+export async function cleanupJob(
+  rawPayload: Record<string, unknown>,
+  ctx: JobContext,
+  db: DbConnection,
+): Promise<void> {
+  const payload = rawPayload as SessionCleanupPayload; // @cast-boundary engine-payload
+  const olderThanDaysRaw = payload.olderThanDays ?? DEFAULT_OLDER_THAN_DAYS;
+  const olderThanDays = Number(olderThanDaysRaw);
+  if (!Number.isFinite(olderThanDays) || olderThanDays < 0 || !Number.isInteger(olderThanDays)) {
+    throw new InternalError({
+      message: `[sessions:cleanup] olderThanDays must be a non-negative integer (got ${String(olderThanDaysRaw)})`,
+    });
+  }
+  const batchSize = payload.batchSize ?? DEFAULT_BATCH_SIZE;
+  const deadline = payload.maxDurationMs
+    ? Date.now() + payload.maxDurationMs
+    : Number.POSITIVE_INFINITY;
+
+  let deleted = 0;
+  let batchesProcessed = 0;
+  let stoppedReason: SessionCleanupResult["stoppedReason"] = "empty";
+
+  while (true) {
+    if (ctx.signal?.aborted) {
+      stoppedReason = "signal";
+      break;
+    }
+    if (Date.now() >= deadline) {
+      stoppedReason = "timeout";
+      break;
+    }
+
+    const batchDeleted = await deleteStaleSessionsBatch(db, olderThanDays, batchSize);
+    if (batchDeleted === 0) break;
+
+    deleted += batchDeleted;
+    batchesProcessed++;
+
+    if (batchDeleted < batchSize) break;
+  }
+
+  const result: SessionCleanupResult = { deleted, batchesProcessed, stoppedReason };
+  ctx.log?.info?.(`[sessions:cleanup] complete: ${JSON.stringify(result)}`);
+}

package/packages/bundled-features/src/sessions/handlers/detail.query.ts

@@ -0,0 +1,51 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { decryptStoredPii } from "../../shared/index.js";
+import { userSessionTable } from "../schema/user-session.js";
+
+// Admin single-session inspector — mirrors list.query's decrypt handling for
+// the one-row case. ctx.db (TenantDb) applies tenant-scoping automatically.
+const sessionRowSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  createdAt: z.unknown(),
+  expiresAt: z.unknown(),
+  revokedAt: z.unknown(),
+  ip: z.string().nullable(),
+  userAgent: z.string().nullable(),
+});
+
+export const detailQuery = defineQueryHandler({
+  name: "user-session:detail",
+  schema: z.object({ id: z.uuid() }),
+  access: { roles: access.admin },
+  description:
+    "Loads one session of the active tenant by its id with owner, timestamps and decrypted IP/user-agent; use it when an admin investigates a specific session found through the session list.",
+  // Decrypted IP and user-agent.
+  agent: { risk: "high" },
+  outputSchema: sessionRowSchema.nullable(),
+  handler: async (query, ctx) => {
+    const row = await fetchOne<{
+      id: string;
+      userId: string;
+      createdAt: unknown;
+      expiresAt: unknown;
+      revokedAt: unknown;
+      ip: string | null;
+      userAgent: string | null;
+    }>(ctx.db, userSessionTable, { id: query.payload.id });
+    if (!row) return null;
+    return {
+      id: row.id,
+      userId: row.userId,
+      createdAt: row.createdAt,
+      expiresAt: row.expiresAt,
+      revokedAt: row.revokedAt,
+      ip: row.ip ? await decryptStoredPii(row.ip, "ip", "sessions:detail") : row.ip,
+      userAgent: row.userAgent
+        ? await decryptStoredPii(row.userAgent, "userAgent", "sessions:detail")
+        : row.userAgent,
+    };
+  },
+});

package/packages/bundled-features/src/sessions/handlers/list.query.ts

@@ -0,0 +1,92 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  access,
+  definePagedQueryHandler,
+  MAX_LIST_LIMIT,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { decryptStoredPii } from "../../shared/index.js";
+import { userSessionTable } from "../schema/user-session.js";
+
+// `sort` arrives raw from the client's query string. selectMany's orderBy
+// has no column-existence check — an unrecognised field just gets
+// snake_cased and quoted as-is (bun-db/query.ts columnOf) — so this
+// allowlist is what stops a client sorting by ip/userAgent or any other
+// non-exposed column.
+const SORTABLE_COLUMNS = ["id", "userId", "createdAt", "expiresAt", "revokedAt"] as const;
+type SortableColumn = (typeof SORTABLE_COLUMNS)[number];
+
+function isSortableColumn(value: string): value is SortableColumn {
+  return (SORTABLE_COLUMNS as readonly string[]).includes(value);
+}
+
+// Admin view of every session in the active tenant. ctx.db (TenantDb)
+// applies tenant-scoping automatically on selects from tables with a
+// tenantId column. Includes revoked rows; UI shows revokedAt distinct.
+// No cursor — nextCursor is always null; `limit` only caps the page size,
+// it doesn't offset into a further one.
+export const listQuery = definePagedQueryHandler({
+  name: "user-session:list",
+  schema: z.object({
+    limit: z.number().int().nonnegative().max(MAX_LIST_LIMIT).optional(),
+    sort: z.string().optional(),
+    sortDirection: z.enum(["asc", "desc"]).optional(),
+  }),
+  access: { roles: access.admin },
+  description:
+    "Lists every session in the active tenant, live and revoked, sortable by id, user, creation, expiry or revocation, for an admin auditing who is signed in.",
+  outputSchema: z.object({
+    rows: z.array(
+      z.object({
+        id: z.string(),
+        userId: z.string(),
+        createdAt: z.unknown(),
+        expiresAt: z.unknown(),
+        revokedAt: z.unknown(),
+        ip: z.string().nullable(),
+        userAgent: z.string().nullable(),
+      }),
+    ),
+    nextCursor: z.string().nullable(),
+  }),
+  handler: async (query, ctx) => {
+    const requestedSort = query.payload.sort;
+    const sortColumn: SortableColumn =
+      requestedSort !== undefined && isSortableColumn(requestedSort) ? requestedSort : "createdAt";
+    const rows = await selectMany<{
+      id: string;
+      userId: string;
+      createdAt: unknown;
+      expiresAt: unknown;
+      revokedAt: unknown;
+      ip: string | null;
+      userAgent: string | null;
+    }>(ctx.db, userSessionTable, undefined, {
+      // `id` as a tie-breaker keeps row order (and, with `limit` set, row
+      // selection) deterministic across identical requests — sortColumn
+      // alone isn't unique (e.g. many NULL revokedAt, or equal timestamps).
+      orderBy:
+        sortColumn === "id"
+          ? { col: "id", direction: query.payload.sortDirection ?? "desc" }
+          : [
+              { col: sortColumn, direction: query.payload.sortDirection ?? "desc" },
+              { col: "id", direction: "asc" },
+            ],
+      ...(query.payload.limit !== undefined && { limit: query.payload.limit }),
+    });
+    const decryptedRows = await Promise.all(
+      rows.map(async (r) => ({
+        id: r.id,
+        userId: r.userId,
+        createdAt: r.createdAt,
+        expiresAt: r.expiresAt,
+        revokedAt: r.revokedAt,
+        ip: r.ip ? await decryptStoredPii(r.ip, "ip", "sessions:list") : r.ip,
+        userAgent: r.userAgent
+          ? await decryptStoredPii(r.userAgent, "userAgent", "sessions:list")
+          : r.userAgent,
+      })),
+    );
+    return { rows: decryptedRows, nextCursor: null };
+  },
+});

package/packages/bundled-features/src/sessions/handlers/mine.query.ts

@@ -0,0 +1,67 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { definePagedQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { decryptStoredPii } from "../../shared/index.js";
+import { userSessionTable } from "../schema/user-session.js";
+
+// "My live sessions" — the backing data for a devices/sessions UI. Returns
+// ONLY the current user's own, currently-live sessions, ordered by most-
+// recently-used first. Revoked rows excluded (revokedAt IS NULL). Paged
+// envelope so the self-service projectionList screen can bind to it; a user's
+// live-session count is small, so there is a single page (nextCursor null).
+export const mineQuery = definePagedQueryHandler({
+  name: "user-session:mine",
+  schema: z.object({}),
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user lists only their own live sessions; the query filters " +
+        "userSessionTable by the caller's own userId",
+    },
+  },
+  description:
+    "Lists the calling user's own still-live sessions, newest first, each flagged whether it is the one making the request; use it to show a user their signed-in devices.",
+  outputSchema: z.object({
+    rows: z.array(
+      z.object({
+        id: z.string(),
+        createdAt: z.unknown(),
+        expiresAt: z.unknown(),
+        ip: z.string().nullable(),
+        userAgent: z.string().nullable(),
+        current: z.boolean(),
+      }),
+    ),
+    nextCursor: z.string().nullable(),
+  }),
+  handler: async (query, ctx) => {
+    const rows = await selectMany<{
+      id: string;
+      createdAt: unknown;
+      expiresAt: unknown;
+      ip: string | null;
+      userAgent: string | null;
+    }>(
+      ctx.db,
+      userSessionTable,
+      { userId: query.user.id, revokedAt: null },
+      {
+        orderBy: { col: "createdAt", direction: "desc" },
+      },
+    );
+    const currentSid = query.user.sid;
+    const decryptedRows = await Promise.all(
+      rows.map(async (r) => ({
+        id: r.id,
+        createdAt: r.createdAt,
+        expiresAt: r.expiresAt,
+        ip: r.ip ? await decryptStoredPii(r.ip, "ip", "sessions:mine") : r.ip,
+        userAgent: r.userAgent
+          ? await decryptStoredPii(r.userAgent, "userAgent", "sessions:mine")
+          : r.userAgent,
+        current: currentSid === r.id,
+      })),
+    );
+    return { rows: decryptedRows, nextCursor: null };
+  },
+});

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

@@ -0,0 +1,122 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { access, defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { append } from "@cosmicdrift/kumiko-framework/event-store";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "temporal-polyfill";
+import * as z from "zod";
+import { userSessionTable } from "../schema/user-session.js";
+import {
+  SESSION_REVOKED_AGGREGATE_TYPE,
+  SESSION_REVOKED_EVENT_QN,
+  sessionRevokedSchema,
+} from "../session-revoked-event.js";
+
+const REVOKE_ALL_SESSIONS_REASON =
+  "revokes the target user's sessions in every tenant and appends the audit event on the SYSTEM stream";
+
+// Mass-revoke ALL live sessions for a target user — privileged-only.
+// 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. A caller that IS the end-user (an admin
+// editing their own roles) passes `exceptSessionId` to keep that one
+// session alive; the event then carries keptSessionId so the SSE streams of
+// that session stay open too.
+//
+// Tenant-scope: the userSession schema persists tenantId per row (a user
+// can have sessions in multiple tenants). Omitting `tenantId` revokes
+// cross-tenant because "account restriction" is a global user-level
+// statement (the forget path is global too, see the User-Entity special
+// doc). Passing `tenantId` narrows the UPDATE to that tenant's rows only —
+// used by tenant-membership removal, where a multi-tenant user must stay
+// logged in to tenants they're still a member of.
+export const revokeAllForUserWrite = defineWriteHandler({
+  name: "user-session:revoke-all-for-user",
+  schema: z.object({
+    userId: z.string().min(1),
+    tenantId: z.string().min(1).optional(),
+    exceptSessionId: z.uuid().optional(),
+  }),
+  access: { roles: access.privileged },
+  description:
+    "Irreversibly signs a named user out of all their live sessions, across every tenant unless a tenantId narrows it, optionally sparing one session (exceptSessionId); use it for operator actions such as freezing or banning an account, or a role change that must not end the editor's own session.",
+  agent: { risk: "high" },
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason: REVOKE_ALL_SESSIONS_REASON,
+  },
+  handler: async (event, ctx) => {
+    const runner = ctx.db.unsafeRaw(REVOKE_ALL_SESSIONS_REASON);
+    const updated = await updateMany<{ id: string }>(
+      runner,
+      userSessionTable,
+      { revokedAt: Temporal.Now.instant() },
+      {
+        userId: event.payload.userId,
+        revokedAt: null,
+        ...(event.payload.tenantId !== undefined && { tenantId: event.payload.tenantId }),
+        ...(event.payload.exceptSessionId !== undefined && {
+          id: { ne: event.payload.exceptSessionId },
+        }),
+      },
+    );
+
+    // 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 eventDef = ctx.registry.getEvent(SESSION_REVOKED_EVENT_QN);
+      if (!eventDef) {
+        return writeFailure(
+          new UnprocessableError("session_revoked_event_not_registered", {
+            details: { eventQn: SESSION_REVOKED_EVENT_QN },
+          }),
+        );
+      }
+      const payload = sessionRevokedSchema.parse({
+        userId: event.payload.userId,
+        sessionIds: updated.map((row) => row.id),
+        ...(event.payload.exceptSessionId !== undefined && {
+          keptSessionId: event.payload.exceptSessionId,
+        }),
+      });
+      const reqCtx = requestContext.get();
+      await append(runner, {
+        aggregateId: generateId(),
+        aggregateType: SESSION_REVOKED_AGGREGATE_TYPE,
+        tenantId: SYSTEM_TENANT_ID,
+        expectedVersion: 0,
+        type: SESSION_REVOKED_EVENT_QN,
+        eventVersion: eventDef.version,
+        payload,
+        metadata: {
+          userId: event.user.id,
+          ...(reqCtx?.requestId ? { requestId: reqCtx.requestId } : {}),
+          ...(reqCtx?.correlationId ? { correlationId: reqCtx.correlationId } : {}),
+          ...(reqCtx?.causationId ? { causationId: reqCtx.causationId } : {}),
+        },
+      });
+    }
+
+    return {
+      isSuccess: true as const,
+      data: { count: updated.length, userId: event.payload.userId },
+    };
+  },
+});