@cosmicdrift/kumiko-bundled-features 0.149.2 → 0.151.0

package/src/auth-mfa/web/mfa-enable-screen.tsx

@@ -9,7 +9,14 @@
 
 import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
-import QRCode from "qrcode";
+// qrcode's package.json#browser remap avoids Node-only deps (yargs/pngjs)
+// for bundlers that honor it — Metro doesn't, hence the explicit subpath.
+// @types/qrcode only covers the main "qrcode" entry, not this subpath, and
+// TypeScript can't auto-discover an ambient .d.ts sibling from inside a
+// node_modules package (consuming apps typecheck this raw .tsx source).
+// Apps mounting MfaEnableScreen need their own local ambient shim — see
+// qrcode-browser.d.ts in this directory for the declaration to copy.
+import QRCode from "qrcode/lib/browser";
 import { type ReactNode, useState } from "react";
 // kumiko-lint-ignore cross-feature-import client-only hook, the feature's server barrel has no web/ re-export
 import { useSession } from "../../auth-email-password/web";
@@ -65,42 +72,51 @@ export function MfaEnableScreen({
   const startSetup = async (): Promise<void> => {
     setBusy(true);
     setError(null);
-    const res = await dispatcher.write<EnableStartResponse>(AuthMfaHandlers.enableStart, {
-      accountLabel: session.user?.email ?? "",
-    });
-    if (!res.isSuccess) {
+    try {
+      const res = await dispatcher.write<EnableStartResponse>(AuthMfaHandlers.enableStart, {
+        accountLabel: session.user?.email ?? "",
+      });
+      if (!res.isSuccess) {
+        setError(res.error.code);
+        return;
+      }
+      const qrSvg = await QRCode.toString(res.data.otpauthUri, { type: "svg" });
+      setSetup({
+        setupToken: res.data.setupToken,
+        secretParam: extractSecret(res.data.otpauthUri),
+        recoveryCodes: res.data.recoveryCodes,
+        qrSvg,
+      });
+      setAcknowledged(false);
+      setCode("");
+    } catch {
+      setError("setup_failed");
+    } finally {
       setBusy(false);
-      setError(res.error.code);
-      return;
     }
-    const qrSvg = await QRCode.toString(res.data.otpauthUri, { type: "svg" });
-    setBusy(false);
-    setSetup({
-      setupToken: res.data.setupToken,
-      secretParam: extractSecret(res.data.otpauthUri),
-      recoveryCodes: res.data.recoveryCodes,
-      qrSvg,
-    });
-    setAcknowledged(false);
-    setCode("");
   };
 
   const confirmSetup = async (): Promise<void> => {
     if (!setup) return;
     setBusy(true);
     setError(null);
-    const res = await dispatcher.write(AuthMfaHandlers.enableConfirm, {
-      setupToken: setup.setupToken,
-      code,
-    });
-    setBusy(false);
-    if (!res.isSuccess) {
-      setError(res.error.code);
-      return;
+    try {
+      const res = await dispatcher.write(AuthMfaHandlers.enableConfirm, {
+        setupToken: setup.setupToken,
+        code,
+      });
+      if (!res.isSuccess) {
+        setError(res.error.code);
+        return;
+      }
+      setEnabled(true);
+      setSetup(null);
+      onEnabled?.();
+    } catch {
+      setError("setup_failed");
+    } finally {
+      setBusy(false);
     }
-    setEnabled(true);
-    setSetup(null);
-    onEnabled?.();
   };
 
   const content = (

package/src/auth-mfa/web/mfa-error-keys.ts

@@ -7,17 +7,19 @@
 // each re-deriving the key ad hoc (enable-screen used to template-string
 // the raw snake_case code straight into the key, which never matched the
 // camelCase keys actually registered below).
+import { AuthMfaErrorCodes } from "../constants";
+
 export function mfaManageErrorKey(code: string): string {
   switch (code) {
-    case "invalid_totp_code":
+    case AuthMfaErrorCodes.invalidTotpCode:
       return "auth.mfa.errors.invalidCode";
-    case "invalid_recovery_code":
+    case AuthMfaErrorCodes.invalidRecoveryCode:
       return "auth.mfa.errors.invalidRecoveryCode";
-    case "mfa_already_enabled":
+    case AuthMfaErrorCodes.mfaAlreadyEnabled:
       return "auth.mfa.errors.mfaAlreadyEnabled";
-    case "mfa_not_enabled":
+    case AuthMfaErrorCodes.mfaNotEnabled:
       return "auth.mfa.errors.mfaNotEnabled";
-    case "invalid_setup_token":
+    case AuthMfaErrorCodes.invalidSetupToken:
       return "auth.mfa.errors.invalidSetupToken";
     default:
       return "auth.mfa.errors.verifyFailed";

package/src/auth-mfa/web/mfa-verify-screen.tsx

@@ -21,6 +21,11 @@ export type MfaVerifyScreenProps = {
    *  refreshed. Optional — apps that swap this screen back out purely on
    *  session.status changing to "authenticated" don't need it. */
   readonly onSuccess?: () => void;
+  // Some failures (challenge_expired, too_many_attempts) have no retry path —
+  // the challengeToken is dead. Without this, the host has no way back to
+  // login short of a full page reload. Optional: apps that always mount
+  // this screen fresh per challenge can omit it.
+  readonly onCancel?: () => void;
 };
 
 function reasonToKey(reason: string): string {
@@ -47,6 +52,7 @@ export function MfaVerifyScreen({
   subtitle,
   submitLabel,
   onSuccess,
+  onCancel,
 }: MfaVerifyScreenProps): ReactNode {
   const t = useTranslation();
   const { Form, Field, Input, Button, Banner } = usePrimitives();
@@ -99,6 +105,11 @@ export function MfaVerifyScreen({
               ? t("auth.mfa.verify.submitting")
               : (submitLabel ?? t("auth.mfa.verify.submit"))}
           </Button>
+          {onCancel ? (
+            <Button type="button" variant="secondary" onClick={onCancel} disabled={submitting}>
+              {t("auth.mfa.verify.backToLogin")}
+            </Button>
+          ) : null}
         </Form>
       </div>
     </AuthCard>

package/src/auth-mfa/web/qrcode-browser.d.ts

@@ -0,0 +1,7 @@
+// @types/qrcode only declares the main "qrcode" entry, not the browser-only
+// subpath (see mfa-enable-screen.tsx's import — the main entry pulls in
+// Node-only deps like yargs/pngjs via qrcode's own package.json#browser
+// remap, which Metro doesn't honor). Same runtime shape, just re-typed.
+declare module "qrcode/lib/browser" {
+  export * from "qrcode";
+}

package/src/auth-mfa-user-data/__tests__/hooks.integration.test.ts

@@ -20,6 +20,7 @@ import { currentTotpCode } from "../../auth-mfa/totp";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant";
 import { createUserFeature } from "../../user/feature";
 import { userEntity } from "../../user/schema/user";
 import { userMfaDeleteHook, userMfaExportHook } from "../hooks";
@@ -36,6 +37,7 @@ beforeAll(async () => {
     features: [
       createConfigFeature(),
       createUserFeature(),
+      createTenantFeature(),
       createAuthMfaFeature({
         setupTokenSecret: SETUP_TOKEN_SECRET,
         issuer: "Kumiko Test",

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

@@ -131,17 +131,34 @@ const ordersFeature = defineFeature("orders", (r) => {
   });
 });
 
+// r.configKey() shorthand — single-key sibling of r.config({keys}), same
+// wiring end-to-end (registry → resolver → ctx.config). No seeds needed here.
+const configKeyDemoFeature = defineFeature("configkeydemo", (r) => {
+  r.requires("config");
+  const betaEnabled = r.configKey(
+    "betaEnabled",
+    createTenantConfig("boolean", { default: false, write: access.roles("Admin") }),
+  );
+  return { betaEnabled };
+});
+
 // Probe feature: a real writeHandler reads two configs through ctx.config
 // so the dispatcher-wiring path is exercised end-to-end (not just the
 // factory in isolation). Captures the resolved values for the test to assert.
-const probe: { orders: number | undefined; push: boolean | undefined } = {
+const probe: {
+  orders: number | undefined;
+  push: boolean | undefined;
+  betaEnabled: boolean | undefined;
+} = {
   orders: undefined,
   push: undefined,
+  betaEnabled: undefined,
 };
 const probeFeature = defineFeature("probe", (r) => {
   r.requires("config");
   r.requires("orders");
   r.requires("notifications");
+  r.requires("configkeydemo");
 
   r.writeHandler(
     "read-config",
@@ -150,7 +167,11 @@ const probeFeature = defineFeature("probe", (r) => {
       if (!ctx.config) throw new Error("ctx.config not wired — _configAccessorFactory missing");
       probe.orders = await ctx.config(ordersFeature.exports.maxOrderCount);
       probe.push = await ctx.config(notificationsFeature.exports.pushEnabled);
-      return { isSuccess: true, data: { orders: probe.orders, push: probe.push } };
+      probe.betaEnabled = await ctx.config(configKeyDemoFeature.exports.betaEnabled);
+      return {
+        isSuccess: true,
+        data: { orders: probe.orders, push: probe.push, betaEnabled: probe.betaEnabled },
+      };
     },
     { access: { openToAll: true } },
   );
@@ -267,6 +288,7 @@ beforeAll(async () => {
       notificationsFeature,
       ordersFeature,
       integrationFeature,
+      configKeyDemoFeature,
       probeFeature,
       seedFeature,
       transportFeature,
@@ -781,12 +803,38 @@ describe("ctx.config() in handler context", () => {
     // Reset so prior test order doesn't pollute the assertion.
     probe.orders = undefined;
     probe.push = undefined;
+    probe.betaEnabled = undefined;
     await stack.http.writeOk("probe:write:read-config", {}, tenantAdmin);
     // The probe handler ran ctx.config(handle) for both keys — typeof
     // catches the regression where the handle path silently returns the
     // broad union instead of the narrowed primitive.
     expect(typeof probe.orders).toBe("number");
     expect(typeof probe.push).toBe("boolean");
+    // r.configKey()'s handle goes through the exact same ctx.config() path.
+    // (value-level check — true vs. false — is covered by the next test,
+    // which reads via configFn without the narrowing hazard of a plain
+    // `undefined`-initialized probe field.)
+    expect(typeof probe.betaEnabled).toBe("boolean");
+  });
+
+  test("r.configKey() value is settable/readable via ctx.config, same as r.config", async () => {
+    expect(configKeyDemoFeature.exports.betaEnabled.name).toBe("configkeydemo:config:beta-enabled");
+
+    const configFn = createConfigAccessor(
+      stack.registry,
+      resolver,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+    expect(await configFn(configKeyDemoFeature.exports.betaEnabled)).toBe(false);
+
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: "configkeydemo:config:beta-enabled", value: true },
+      tenantAdmin,
+    );
+    expect(await configFn(configKeyDemoFeature.exports.betaEnabled)).toBe(true);
   });
 });
 

package/src/config/handlers/cascade.query.ts

@@ -2,6 +2,7 @@ import {
   type ConfigCascade,
   type ConfigCascadeLevel,
   defineQueryHandler,
+  isEncryptedAtRest,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
@@ -59,7 +60,7 @@ export const cascadeQuery = defineQueryHandler({
 
       // backing="secrets" is masked like encrypted — the resolver revealed the
       // plaintext for internal reads, but it must never reach the cascade UI.
-      if (keyDef.encrypted || keyDef.backing === "secrets") {
+      if (isEncryptedAtRest(keyDef)) {
         const maskedLevels: ConfigCascadeLevel[] = cascade.levels.map((l) => ({
           ...l,
           value: l.hasValue ? MASKED : l.value,

package/src/config/handlers/values.query.ts

@@ -3,6 +3,7 @@ import {
   type ConfigScope,
   type ConfigValueSource,
   defineQueryHandler,
+  isEncryptedAtRest,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
@@ -63,7 +64,7 @@ export const valuesQuery = defineQueryHandler({
       // key so the plaintext (which the resolver revealed for internal reads)
       // never reaches the UI response.
       let value: string | number | boolean | undefined;
-      if (keyDef.encrypted || keyDef.backing === "secrets") {
+      if (isEncryptedAtRest(keyDef)) {
         value = cascade.value !== undefined ? MASKED : undefined;
       } else {
         value = cascade.value;

package/src/file-foundation/__tests__/feature.test.ts

@@ -21,10 +21,10 @@ describe("fileFoundationFeature — shape", () => {
 
 describe("fileFoundationFeature.exports — typed handles", () => {
   test("exposes only the provider-selector config-key", () => {
-    const keys = fileFoundationFeature.exports.configKeys;
-    expect(keys.provider).toBeDefined();
-    expect((keys as Record<string, unknown>)["bucket"]).toBeUndefined();
-    expect((keys as Record<string, unknown>)["region"]).toBeUndefined();
+    expect(fileFoundationFeature.exports.providerConfigKey).toBeDefined();
+    expect(fileFoundationFeature.exports.providerConfigKey.name).toBe(
+      "file-foundation:config:provider",
+    );
   });
 });
 

package/src/file-foundation/feature.ts

@@ -54,18 +54,17 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
     },
   });
 
-  const configKeys = r.config({
-    keys: {
-      provider: createTenantConfig("text", {
-        default: "",
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-        read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-      }),
-    },
-  });
+  const providerConfigKey = r.configKey(
+    "provider",
+    createTenantConfig("text", {
+      default: "",
+      write: access.roles("TenantAdmin", "SystemAdmin"),
+      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+    }),
+  );
   // Readiness gating: provider-plugins' required keys/secrets count only
   // while their plugin is the one this key selects.
-  r.extensionSelector(EXT_FILE_PROVIDER, configKeys.provider);
+  r.extensionSelector(EXT_FILE_PROVIDER, providerConfigKey);
 
-  return { configKeys };
+  return { providerConfigKey };
 });

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -9,7 +9,9 @@
 //   3. PII-Encrypt (from/to/cc/subject/snippet) VOR dem append —
 //      Event-Log UND Projection tragen Ciphertext (#800-Muster).
 //   4. inbound-message-received-append (Inline-Projection schreibt
-//      read_inbound_messages in derselben TX).
+//      read_inbound_messages in derselben TX). Savepoint-scoped
+//      (ctx.tryAppendEvent) — a losing concurrent ingest for the same
+//      messageAggId returns { duplicate: true } instead of failing the TX.
 //   5. Thread-Rollup: mail-thread-updated-append mit neu berechnetem
 //      Snapshot (count+1, max(lastMessageAt)) — die apply ist ein
 //      dummer UPSERT.
@@ -199,13 +201,24 @@ export const ingestMessageHandler: WriteHandlerDef = {
       providerName: payload.providerName,
       providerCursor: payload.providerCursor,
     };
-    await ctx.unsafeAppendEvent({
+    const messageAppend = await ctx.tryAppendEvent({
       aggregateId: messageAggId,
       aggregateType: INBOUND_MESSAGE_AGGREGATE_TYPE,
       type: INBOUND_MESSAGE_RECEIVED_EVENT_QN,
       payload: messageEventPayload,
       headers: messageHeaders,
     });
+    if (!messageAppend.ok) {
+      // Lost the race against a concurrent ingest for the same messageAggId
+      // (Watch-Push vs. Poll-Reconciliation overlap). The winner already
+      // writes thread-rollup + seen-anchor for this message — steps 5+6
+      // skip here. tryAppendEvent's savepoint keeps this TX usable despite
+      // the caught VersionConflictError (see ctx.tryAppendEvent doc).
+      return {
+        isSuccess: true as const,
+        data: { duplicate: true as const, inboundMessageAggregateId: messageAggId },
+      };
+    }
 
     // ---------------------------------------------------------------
     // 5. Thread-Rollup. Der Handler berechnet den NEUEN Snapshot

package/src/legal-pages/feature.ts

@@ -97,7 +97,8 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
               { slug: route.slug, lang: route.lang },
               SYSTEM_TENANT_ID,
             )) as TextBlockQueryResult;
-          } catch {
+          } catch (err) {
+            console.error(`legal-pages: text-content query failed for slug="${route.slug}"`, err);
             return c.text("legal page unavailable", 503);
           }
 

package/src/mail-foundation/__tests__/feature.test.ts

@@ -29,11 +29,10 @@ describe("mailFoundationFeature — shape", () => {
 
 describe("mailFoundationFeature.exports — typed handles", () => {
   test("exposes only the provider-selector config-key", () => {
-    const keys = mailFoundationFeature.exports.configKeys;
-    expect(keys.provider).toBeDefined();
-    // No host/port/from/authUser — those live in the provider-plugin.
-    expect((keys as Record<string, unknown>)["host"]).toBeUndefined();
-    expect((keys as Record<string, unknown>)["port"]).toBeUndefined();
+    expect(mailFoundationFeature.exports.providerConfigKey).toBeDefined();
+    expect(mailFoundationFeature.exports.providerConfigKey.name).toBe(
+      "mail-foundation:config:provider",
+    );
   });
 });
 

package/src/mail-foundation/feature.ts

@@ -130,32 +130,31 @@ export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
     },
   });
 
-  const configKeys = r.config({
-    keys: {
-      // Provider-selector. Default empty so the boot-validator throws
-      // if a tenant tries to send mail without first picking + setting
-      // up a provider — better than a silent fallback.
-      // The actual list of valid values lives in the registered plugins,
-      // not here — Designer-UI can render `getExtensionUsages
-      // ("mailTransport").map(u => u.entityName)` as the option-list.
-      provider: createTenantConfig("text", {
-        default: "",
-        // required: ohne gewählten Provider wirft createTransportForTenant —
-        // readiness meldete vorher ready:true und der erste Mail-Send
-        // lieferte den UnconfiguredError (280/1).
-        required: true,
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-        read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-      }),
-    },
-  });
+  // Provider-selector. Default empty so the boot-validator throws if a
+  // tenant tries to send mail without first picking + setting up a
+  // provider — better than a silent fallback. The actual list of valid
+  // values lives in the registered plugins, not here — Designer-UI can
+  // render `getExtensionUsages("mailTransport").map(u => u.entityName)`
+  // as the option-list.
+  const providerConfigKey = r.configKey(
+    "provider",
+    createTenantConfig("text", {
+      default: "",
+      // required: ohne gewählten Provider wirft createTransportForTenant —
+      // readiness meldete vorher ready:true und der erste Mail-Send
+      // lieferte den UnconfiguredError (280/1).
+      required: true,
+      write: access.roles("TenantAdmin", "SystemAdmin"),
+      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+    }),
+  );
   // Readiness gating: transport-plugins' required keys/secrets count only
   // while their plugin is the one this key selects.
-  r.extensionSelector("mailTransport", configKeys.provider);
+  r.extensionSelector("mailTransport", providerConfigKey);
 
   return {
     /** Config-key-handle for the provider-selector. */
-    configKeys,
+    providerConfigKey,
   };
 });
 
@@ -190,7 +189,7 @@ export async function createTransportForTenant(
   }
 
   const provider = requireDefined(
-    await ctxConfig(mailFoundationFeature.exports.configKeys.provider),
+    await ctxConfig(mailFoundationFeature.exports.providerConfigKey),
     FEATURE_NAME,
     "provider",
   ) as string; // @cast-boundary engine-payload

package/src/managed-pages/feature.ts

@@ -15,6 +15,7 @@ import {
   renderSafeMarkdown,
   wrapInLayout,
 } from "../page-render";
+import type { SystemQueryFn } from "../shared";
 import { BRANDING_KEYS, BRANDING_QUERY_QN, CUSTOM_CSS_KEY, coerceBranding } from "./branding";
 import { createBrandingQuery } from "./handlers/branding.query";
 import { bySlugQuery } from "./handlers/by-slug.query";
@@ -38,12 +39,6 @@ const PUBLIC_PAGE_CACHE = { kind: "revalidate", maxAgeSeconds: 60 } as const;
 // Handlers, symmetrisch zum legal-pages-Muster).
 const BY_SLUG_QN = "managed-pages:query:by-slug";
 
-// Minimal shape of the httpRoute handler's `{ systemQuery }` dep — mirrors
-// http-route.ts's signature. Not importing HttpRouteHandlerDeps itself: it
-// isn't part of the engine's public surface (only the httpRoute-
-// registration types are; same convention as seo/feature.ts's FetchApp).
-type SystemQueryFn = (type: string, payload: unknown, tenantId: string) => Promise<unknown>;
-
 // Raw Handler-Return von bySlugQuery (published-only) — systemQuery dispatcht
 // direkt gegen den Handler, keine `{data}`-Envelope wie am /api/query-Wire.
 type BySlugQueryResult = {

package/src/seo/feature.ts

@@ -6,6 +6,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { LEGAL_ROUTES } from "../legal-pages";
 import { cachedSecurePageResponse } from "../page-render";
+import type { SystemQueryFn } from "../shared";
 import { SEO_CONFIG_KEYS, SEO_DEFAULT_PATHS } from "./constants";
 import { seoConfigQuery } from "./handlers/seo-config.query";
 import { buildLlmsTxt } from "./llms-txt";
@@ -19,12 +20,6 @@ const SEO_CACHE = { kind: "revalidate", maxAgeSeconds: 300 } as const;
 const MANAGED_PAGES_BY_TENANT_PUBLISHED_QN = "managed-pages:query:by-tenant-published";
 const SEO_CONFIG_QUERY_QN = "seo:query:config";
 
-// Minimal shape of the httpRoute handler's `{ systemQuery }` dep — just
-// enough to force a specific tenant in-process. Not importing
-// HttpRouteHandlerDeps itself: it isn't part of the engine's public surface
-// (only the httpRoute-registration types are).
-type SystemQueryFn = (type: string, payload: unknown, tenantId: string) => Promise<unknown>;
-
 export type ManagedPagesDiscoveryOptions = {
   /** Same per-host tenant resolver the app already passes to
    *  createManagedPagesFeature — needed to X-Tenant-scope the anonymous

package/src/sessions/__tests__/sessions-screens.boot.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config/feature";
+import { createTenantFeature } from "../../tenant";
+import { createUserFeature } from "../../user/feature";
+import { SESSION_DETAIL_SCREEN_ID, SESSION_LIST_SCREEN_ID } from "../constants";
+import { createSessionsFeature } from "../feature";
+
+describe("sessions screens + query access alignment (kumiko-framework#255)", () => {
+  const features = [
+    createConfigFeature(),
+    createUserFeature(),
+    createTenantFeature(),
+    createSessionsFeature(),
+  ];
+
+  test("boot-validates with session-list/session-detail screens registered", () => {
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("session-list is projectionList, session-detail is projectionDetail, both admin-gated", () => {
+    const sessions = createSessionsFeature();
+    const list = sessions.screens[SESSION_LIST_SCREEN_ID];
+    expect(list?.type).toBe("projectionList");
+    const detail = sessions.screens[SESSION_DETAIL_SCREEN_ID];
+    expect(detail?.type).toBe("projectionDetail");
+    for (const screen of [list, detail]) {
+      if (screen && "access" in screen && screen.access && "roles" in screen.access) {
+        expect(screen.access.roles).toEqual(["TenantAdmin", "Admin", "SystemAdmin"]);
+      }
+    }
+  });
+
+  test("session-list row-action navigates to session-detail with entityId 'id'", () => {
+    const sessions = createSessionsFeature();
+    const list = sessions.screens[SESSION_LIST_SCREEN_ID];
+    if (list?.type !== "projectionList") throw new Error("expected projectionList");
+    const openAction = list.rowActions?.find((a) => a.id === "open");
+    if (openAction?.kind !== "navigate") throw new Error("expected a navigate rowAction");
+    expect(openAction.screen).toBe(SESSION_DETAIL_SCREEN_ID);
+    expect(openAction.entityId).toBe("id");
+  });
+
+  test("sessions queries share the admin-or-higher access rule", () => {
+    const sessions = createSessionsFeature();
+    const roles = ["TenantAdmin", "Admin", "SystemAdmin"];
+    expect(rolesOf(sessions.queryHandlers["user-session:list"]?.access)).toEqual(roles);
+    expect(rolesOf(sessions.queryHandlers["user-session:detail"]?.access)).toEqual(roles);
+  });
+});

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

@@ -467,6 +467,50 @@ describe("sessions feature — login → check → revoke → rejected", () => {
     // silent orderBy removal.
     expect(body.data[0]?.id).toBe(aliceAsAdmin.sid);
   });
+
+  // Single-row inspector backing the session-detail screen (kumiko-framework#255).
+  // Same access-gate as session:list (admin-or-higher); verifies field-shape,
+  // decryption of ip/userAgent, and the "unknown id" not-found path.
+  test("session:detail returns one decrypted row for admins, null for an unknown id", async () => {
+    const { userId: aliceId } = await h.seedUser("alice3@example.com", "pw-long-enough");
+
+    await updateRows(
+      stack.db,
+      tenantMembershipsTable,
+      { roles: JSON.stringify(["Admin"]) },
+      { userId: aliceId, tenantId: TENANT },
+    );
+    const aliceAsAdmin = await h.login("alice3@example.com", "pw-long-enough");
+
+    const res = await h.authedPost("/api/query", aliceAsAdmin.token, {
+      type: SessionQueries.detail,
+      payload: { id: aliceAsAdmin.sid },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      data: { id: string; userId: string; revokedAt: string | null } | null;
+    };
+    expect(body.data?.id).toBe(aliceAsAdmin.sid);
+    expect(body.data?.userId).toBe(aliceId);
+    expect(body.data?.revokedAt).toBeNull();
+
+    const missing = await h.authedPost("/api/query", aliceAsAdmin.token, {
+      type: SessionQueries.detail,
+      payload: { id: "00000000-0000-4000-8000-0000deadbeef" },
+    });
+    expect(missing.status).toBe(200);
+    const missingBody = (await missing.json()) as { data: unknown };
+    expect(missingBody.data).toBeNull();
+
+    // Plain User gets the same 403 as session:list — same access-gate.
+    await h.seedUser("bob3@example.com", "pw-long-enough");
+    const bob = await h.login("bob3@example.com", "pw-long-enough");
+    const asUser = await h.authedPost("/api/query", bob.token, {
+      type: SessionQueries.detail,
+      payload: { id: aliceAsAdmin.sid },
+    });
+    expect(asUser.status).toBe(403);
+  });
 });
 
 // Defense-in-depth: the sessionChecker refuses a live sid once the user it

package/src/sessions/__tests__/test-helpers.ts

@@ -12,7 +12,7 @@ import { expect } from "bun:test";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
 import * as jose from "jose";
-import { hashPassword } from "../../auth-email-password/password-hashing";
+import { hashPassword } from "../../shared";
 import { seedTenantMembership } from "../../tenant/seeding";
 import { UserHandlers } from "../../user";