@cosmicdrift/kumiko-bundled-features 0.116.1 → 0.119.0

package/src/crypto-shredding/__tests__/forget-subject.integration.test.ts

@@ -0,0 +1,148 @@
+// crypto-shredding forget-subject — end-to-end over real HTTP dispatch:
+//
+//   - DPO erases a user subject → DEK gone (getKey throws KeyErased),
+//     subject-forgotten audit event appended
+//   - tenant subjects shred the same way
+//   - repeat forget is a no-op erase but still audited
+//   - no KMS configured → 500 with actionable message
+//   - Member role → 403 (DPO/SystemAdmin only)
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  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, testTenantId } from "@cosmicdrift/kumiko-framework/stack";
+import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { SUBJECT_FORGOTTEN_EVENT_NAME } from "../constants";
+import { createCryptoShreddingFeature } from "../feature";
+
+const FORGET = "crypto-shredding:write:forget-subject";
+
+let stack: TestStack;
+let kms: InMemoryKmsAdapter;
+
+const TENANT: TenantId = testTenantId(1);
+const TARGET_USER_ID = "aaaaaaaa-aaaa-4aaa-8aaa-000000000001";
+const TARGET_TENANT_ID = "aaaaaaaa-aaaa-4aaa-8aaa-0000000000a1";
+const REASON = "authority request #42 (Art. 17)";
+
+const dpoUser = {
+  id: "aaaaaaaa-aaaa-4aaa-8aaa-0000000000d1",
+  tenantId: TENANT,
+  roles: ["DataProtectionOfficer"],
+};
+
+const memberUser = {
+  id: "aaaaaaaa-aaaa-4aaa-8aaa-0000000000e1",
+  tenantId: TENANT,
+  roles: ["Member"],
+};
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [createCryptoShreddingFeature()] });
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetTestTables(stack.db, [eventsTable]);
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+async function forgottenEvents(): Promise<Array<{ payload: Record<string, unknown> }>> {
+  return (await selectMany(stack.db, eventsTable, {
+    type: SUBJECT_FORGOTTEN_EVENT_NAME,
+  })) as Array<{ payload: Record<string, unknown> }>;
+}
+
+describe("crypto-shredding :: forget-subject", () => {
+  test("DPO forgets a user subject → key erased + audit event", async () => {
+    const subject = { kind: "user", userId: TARGET_USER_ID } as const;
+    await kms.createKey(subject);
+
+    const result = await stack.http.writeOk<{ subjectKey: string }>(
+      FORGET,
+      { subject, reason: REASON },
+      dpoUser,
+    );
+    expect(result.subjectKey).toBe(`user:${TARGET_USER_ID}`);
+
+    await expect(kms.getKey(subject)).rejects.toThrow("Subject key erased");
+
+    const events = await forgottenEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]?.payload).toMatchObject({
+      subjectKey: `user:${TARGET_USER_ID}`,
+      reason: REASON,
+      forgottenBy: dpoUser.id,
+    });
+  });
+
+  test("tenant subject shreds the same way", async () => {
+    const subject = { kind: "tenant", tenantId: TARGET_TENANT_ID } as const;
+    await kms.createKey({ kind: "tenant", tenantId: TARGET_TENANT_ID as TenantId });
+
+    const result = await stack.http.writeOk<{ subjectKey: string }>(
+      FORGET,
+      { subject, reason: REASON },
+      dpoUser,
+    );
+    expect(result.subjectKey).toBe(`tenant:${TARGET_TENANT_ID}`);
+
+    await expect(
+      kms.getKey({ kind: "tenant", tenantId: TARGET_TENANT_ID as TenantId }),
+    ).rejects.toThrow("Subject key erased");
+  });
+
+  test("repeat forget: erase is a no-op but each attempt is audited", async () => {
+    const subject = { kind: "user", userId: TARGET_USER_ID } as const;
+    await kms.createKey(subject);
+
+    await stack.http.writeOk(FORGET, { subject, reason: REASON }, dpoUser);
+    await stack.http.writeOk(FORGET, { subject, reason: `${REASON} (repeat)` }, dpoUser);
+
+    expect(await forgottenEvents()).toHaveLength(2);
+  });
+
+  test("no KMS configured → 500 with boot hint", async () => {
+    resetPiiSubjectKmsForTests();
+
+    const err = await stack.http.writeErr(
+      FORGET,
+      { subject: { kind: "user", userId: TARGET_USER_ID }, reason: REASON },
+      dpoUser,
+    );
+    expect(err.httpStatus).toBe(500);
+  });
+
+  test("Member role → 403", async () => {
+    const err = await stack.http.writeErr(
+      FORGET,
+      { subject: { kind: "user", userId: TARGET_USER_ID }, reason: REASON },
+      memberUser,
+    );
+    expect(err.httpStatus).toBe(403);
+  });
+
+  test("reason shorter than 10 chars → schema reject", async () => {
+    const err = await stack.http.writeErr(
+      FORGET,
+      { subject: { kind: "user", userId: TARGET_USER_ID }, reason: "short" },
+      dpoUser,
+    );
+    expect(err.httpStatus).toBe(400);
+  });
+});

package/src/crypto-shredding/constants.ts

@@ -0,0 +1,5 @@
+export const CRYPTO_SHREDDING_FEATURE_NAME = "crypto-shredding";
+
+export const SUBJECT_FORGOTTEN_EVENT_NAME = "crypto-shredding:event:subject-forgotten";
+
+export const CRYPTO_SHREDDING_AGGREGATE_TYPE = "crypto-shredding-subject";

package/src/crypto-shredding/feature.ts

@@ -0,0 +1,18 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { CRYPTO_SHREDDING_FEATURE_NAME } from "./constants";
+import { forgetSubjectWrite, subjectForgottenSchema } from "./handlers/forget-subject.write";
+
+export function createCryptoShreddingFeature(): FeatureDefinition {
+  return defineFeature(CRYPTO_SHREDDING_FEATURE_NAME, (r) => {
+    r.describe(
+      "Operator-level crypto-shredding trigger. `forget-subject` erases a user or tenant subject key in the configured KMS adapter, making every PII field encrypted under it permanently unreadable (reads render the `[[erased]]` sentinel), and appends a `subject-forgotten` audit event. Requires a KMS adapter (`runProdApp({ kms })`). The automated Art.-17 deletion pipeline in `user-data-rights` erases keys itself; this command covers manual forgets (authority requests, operator recovery, tenant destroy).",
+    );
+    r.uiHints({
+      displayLabel: "Crypto-Shredding",
+      category: "compliance",
+    });
+
+    r.defineEvent("subject-forgotten", subjectForgottenSchema);
+    r.writeHandler(forgetSubjectWrite);
+  });
+}

package/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -0,0 +1,91 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import {
+  configuredPiiSubjectKms,
+  type SubjectId,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { nullBlindIndexesForSubject } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { CRYPTO_SHREDDING_AGGREGATE_TYPE, SUBJECT_FORGOTTEN_EVENT_NAME } from "../constants";
+
+export const subjectIdSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("user"), userId: z.uuid() }),
+  z.object({ kind: z.literal("tenant"), tenantId: z.uuid() }),
+]);
+
+export const forgetSubjectSchema = z.object({
+  subject: subjectIdSchema,
+  reason: z.string().min(10),
+});
+
+export const subjectForgottenSchema = z.object({
+  subjectKey: z.string().min(1),
+  reason: z.string().min(10),
+  forgottenBy: z.string().min(1),
+});
+
+// Manual crypto-shred for a DPO / platform operator: erases the subject's
+// DEK immediately (all its PII ciphertext becomes unreadable, reads render
+// "[[erased]]") and appends the audit event. Forget is final — the adapter
+// keeps a tombstone, so the subject can never get a new key.
+//
+// The automated Art.-17 path (user-data-rights forget-cleanup) calls
+// kms.eraseKey directly inside its per-user sub-tx; this command is the
+// standalone trigger for cases outside that pipeline (authority requests,
+// tenant-destroy in Sprint 5, operator recovery).
+export const forgetSubjectWrite = defineWriteHandler({
+  name: "forget-subject",
+  schema: forgetSubjectSchema,
+  access: { roles: [ROLES.DataProtectionOfficer, ROLES.SystemAdmin] },
+  handler: async (event, ctx) => {
+    const kms = configuredPiiSubjectKms();
+    if (!kms) {
+      return writeFailure(
+        new InternalError({
+          message:
+            "[crypto-shredding] forget-subject called but no KMS adapter is configured — " +
+            "pass runProdApp({ kms }) / configurePiiSubjectKms(adapter) at boot.",
+        }),
+      );
+    }
+
+    const raw = event.payload.subject;
+    const subject: SubjectId =
+      raw.kind === "user"
+        ? { kind: "user", userId: raw.userId }
+        : { kind: "tenant", tenantId: raw.tenantId as TenantId }; // @cast-boundary uuid-validated command payload → branded id
+    const subjectKey = subjectIdToKey(subject);
+
+    // Erase BEFORE the audit append: if the append throws, the key is gone
+    // but no event exists — a retry is a no-op erase plus the event. The
+    // reverse order could leave an audit trail claiming a shred that never
+    // happened.
+    await kms.eraseKey(subject, {
+      requestId: requestContext.get()?.requestId ?? "crypto-shredding:forget-subject",
+      userId: event.user.id,
+      eraseReason: event.payload.reason,
+    });
+
+    // Blind-Index-Sweep (#818): bidx-Spalten des erased Subjects sofort
+    // nullen — sonst bliebe der deterministische HMAC bis zum nächsten
+    // Rebuild equality-matchbar. Bewusst ctx.db.raw: der Ciphertext-Prefix
+    // adressiert das Subject tenant-übergreifend.
+    await nullBlindIndexesForSubject(ctx.db.raw, ctx.registry.features, subjectKey);
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: raw.kind === "user" ? raw.userId : raw.tenantId,
+      aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
+      type: SUBJECT_FORGOTTEN_EVENT_NAME,
+      payload: {
+        subjectKey,
+        reason: event.payload.reason,
+        forgottenBy: event.user.id,
+      },
+    });
+
+    return { isSuccess: true as const, data: { subjectKey } };
+  },
+});

package/src/crypto-shredding/index.ts

@@ -0,0 +1,11 @@
+export {
+  CRYPTO_SHREDDING_AGGREGATE_TYPE,
+  CRYPTO_SHREDDING_FEATURE_NAME,
+  SUBJECT_FORGOTTEN_EVENT_NAME,
+} from "./constants";
+export { createCryptoShreddingFeature } from "./feature";
+export {
+  forgetSubjectSchema,
+  subjectForgottenSchema,
+  subjectIdSchema,
+} from "./handlers/forget-subject.write";

package/src/delivery/tables.ts

@@ -76,7 +76,7 @@ export const deliveryAttemptsTableMeta: EntityTableMeta = defineUnmanagedTable({
 export const notificationPreferenceEntity = createEntity({
   table: "read_notification_preferences",
   fields: {
-    userId: createTextField({ required: true, pii: true }),
+    userId: createTextField({ required: true, allowPlaintext: "pseudonymous-fk" }),
     notificationType: createTextField({ required: true }), // qualified name or "*"
     channel: createTextField({ required: true }), // "inApp", "email", "push", or "*"
     enabled: createBooleanField({ default: true }),

package/src/mail-foundation/feature.ts

@@ -31,7 +31,10 @@
 // `channel-email` (App-wide-Mail-Sender via delivery) bleibt unangetastet
 // — additive Feature.
 
-import type { EmailTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import {
+  type EmailTransport,
+  withPiiCiphertextGuard,
+} from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   access,
@@ -216,5 +219,5 @@ export async function createTransportForTenant(
         `extension options must be a MailTransportPlugin.`,
     );
   }
-  return usage.options.build(ctx, tenantId);
+  return withPiiCiphertextGuard(await usage.options.build(ctx, tenantId));
 }

package/src/personal-access-tokens/__tests__/feature.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { createPersonalAccessTokensFeature } from "../feature";
+
+describe("createPersonalAccessTokensFeature toggleable-option (tier-gating)", () => {
+  test("without toggleable: feature is always-on (toggleableDefault undefined)", () => {
+    expect(createPersonalAccessTokensFeature({ scopes: {} }).toggleableDefault).toBeUndefined();
+  });
+
+  test("toggleable:{default:false} makes the feature tier-gatable, fail-closed", () => {
+    const feature = createPersonalAccessTokensFeature({
+      scopes: {},
+      toggleable: { default: false },
+    });
+    expect(feature.toggleableDefault).toBe(false);
+  });
+
+  test("toggleable:{default:true} declares toggleable, enabled-by-default", () => {
+    const feature = createPersonalAccessTokensFeature({
+      scopes: {},
+      toggleable: { default: true },
+    });
+    expect(feature.toggleableDefault).toBe(true);
+  });
+});

package/src/personal-access-tokens/__tests__/pat.integration.test.ts

@@ -4,7 +4,15 @@ import {
   createInMemoryLoginRateLimiter,
   type PatResolver,
 } from "@cosmicdrift/kumiko-framework/api";
-import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -202,3 +210,33 @@ describe("PAT auth", () => {
     expect(res.status).toBe(401);
   });
 });
+
+describe("PAT with active KMS (#820): token name is userOwned PII", () => {
+  test("create stores ciphertext at rest, list returns the plaintext name", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    configureBlindIndexKey(Buffer.alloc(32, 7).toString("base64"));
+    try {
+      const actor = await actorFor("kms-pat@example.com");
+      const token = await mintToken(actor);
+
+      const rows = await stack.http.queryOk<Array<{ id: string; name: string }>>(
+        PatQueries.mine,
+        {},
+        actor,
+      );
+      expect(rows[0]?.name).toBe("test");
+
+      const stored = await selectMany<{ name: string }>(stack.db, apiTokenTable, {
+        id: rows[0]?.id,
+      });
+      expect(isPiiCiphertext(stored[0]?.name)).toBe(true);
+
+      // Der Token selbst funktioniert weiter (resolver liest tokenHash, nie name).
+      const res = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+      expect(res.status).toBe(200);
+    } finally {
+      resetPiiSubjectKmsForTests();
+      resetBlindIndexKeyForTests();
+    }
+  });
+});

package/src/personal-access-tokens/feature.ts

@@ -17,6 +17,10 @@ export type PersonalAccessTokensOptions = {
   // Per-token request rate limit for PAT-authenticated calls. Defaults to
   // PAT_DEFAULT_RATE_LIMIT (120/60s). run-prod-app builds the limiter from this.
   readonly rateLimit?: PatRateLimit;
+  /** Make the whole feature tier-gatable via the tier-engine. Use
+   *  { default: false } for fail-closed gating (feature off until a tier grants
+   *  it). Omit to keep PAT always-on (default). */
+  readonly toggleable?: { readonly default: boolean };
 };
 
 export type PatFeatureExports = {
@@ -35,9 +39,13 @@ export function createPersonalAccessTokensFeature(
   const { scopes } = options;
   return defineFeature(PAT_FEATURE, (r) => {
     r.describe(
-      "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `read_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — the resolver is wired via run-prod-app, not the dispatcher.",
+      "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `read_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — the resolver is wired via run-prod-app, not the dispatcher. Pass { toggleable: { default: false } } to tier-gate the whole feature.",
     );
     r.uiHints({ displayLabel: "Personal Access Tokens", category: "identity", recommended: false });
+    // Opt-in tier-gating (mirrors ledger/tags): when set, the feature declares
+    // itself r.toggleable so the dispatcher gate + tier-engine can switch PAT
+    // on/off per tenant. { default: false } = fail-closed until a tier grants it.
+    if (options.toggleable !== undefined) r.toggleable(options.toggleable);
     // Resolver reads memberships + users on every PAT request to build live
     // roles — make both boot-time deps so a mis-wiring fails validateBoot.
     r.requires("user", "tenant");
@@ -46,6 +54,8 @@ export function createPersonalAccessTokensFeature(
     // whose replay (no token events) would wipe every live token (#498/#494).
     r.unmanagedTable(buildEntityTableMeta("api-token", apiTokenEntity), {
       reason: "read_side.api_tokens_direct_write",
+      // create.write encrypts `name` via encryptForDirectWrite (#820).
+      piiEncryptedOnWrite: true,
     });
 
     const handlers = {

package/src/personal-access-tokens/handlers/create.write.ts

@@ -3,8 +3,9 @@ import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
+import { encryptForDirectWrite } from "../../shared";
 import { mintPatToken } from "../hash";
-import { apiTokenTable } from "../schema/api-token";
+import { apiTokenEntity, apiTokenTable } from "../schema/api-token";
 
 // Mint a PAT for the calling user in their active tenant. The plaintext token
 // is returned ONCE (data.token) and never again — only the hash is stored.
@@ -22,20 +23,25 @@ export const createPatWrite = defineWriteHandler({
     const { raw, hash, prefix } = mintPatToken();
     const now = Temporal.Now.instant();
     const id = generateId();
-    await insertOne(ctx.db, apiTokenTable, {
-      id,
-      userId: event.user.id,
-      tenantId: event.user.tenantId,
-      name: event.payload.name,
-      tokenHash: hash,
-      prefix,
-      scopes: JSON.stringify(event.payload.scopes),
-      createdAt: now,
-      expiresAt: event.payload.expiresInDays
-        ? now.add({ hours: 24 * event.payload.expiresInDays })
-        : null,
-      revokedAt: null,
-    });
+    const row = await encryptForDirectWrite(
+      apiTokenEntity,
+      {
+        id,
+        userId: event.user.id,
+        tenantId: event.user.tenantId,
+        name: event.payload.name,
+        tokenHash: hash,
+        prefix,
+        scopes: JSON.stringify(event.payload.scopes),
+        createdAt: now,
+        expiresAt: event.payload.expiresInDays
+          ? now.add({ hours: 24 * event.payload.expiresInDays })
+          : null,
+        revokedAt: null,
+      },
+      "pat:create",
+    );
+    await insertOne(ctx.db, apiTokenTable, row);
     return { isSuccess: true, data: { id, token: raw, prefix } };
   },
 });

package/src/personal-access-tokens/handlers/list.query.ts

@@ -1,6 +1,7 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { decryptStoredPii } from "../../shared";
 import { apiTokenTable } from "../schema/api-token";
 
 // The caller's own tokens — metadata only, never the hash or plaintext.
@@ -25,15 +26,17 @@ export const listPatQuery = defineQueryHandler({
       { userId: query.user.id },
       { orderBy: { col: "createdAt", direction: "desc" } },
     );
-    return rows.map((r) => ({
-      id: r.id,
-      name: r.name,
-      prefix: r.prefix,
-      scopes: parseScopeNames(r.scopes),
-      createdAt: r.createdAt,
-      expiresAt: r.expiresAt,
-      revokedAt: r.revokedAt,
-    }));
+    return Promise.all(
+      rows.map(async (r) => ({
+        id: r.id,
+        name: await decryptStoredPii(r.name, "pat:list"),
+        prefix: r.prefix,
+        scopes: parseScopeNames(r.scopes),
+        createdAt: r.createdAt,
+        expiresAt: r.expiresAt,
+        revokedAt: r.revokedAt,
+      })),
+    );
   },
 });
 

package/src/personal-access-tokens/schema/api-token.ts

@@ -33,7 +33,7 @@ export const apiTokenEntity = createEntity({
       required: true,
       maxLength: 120,
       access: { write: access.privileged },
-      pii: true,
+      userOwned: { ownerField: "userId" },
     }),
     tokenHash: createTextField({
       required: true,

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

@@ -1,6 +1,14 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -538,3 +546,44 @@ describe("sessions feature — locked accounts blocked on a live session", () =>
     expect(res.status).toBe(200);
   });
 });
+
+describe("sessions with active KMS (#820): ip/userAgent are userOwned PII", () => {
+  test("sessionCreator stores ciphertext at rest, mine returns plaintext", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    configureBlindIndexKey(Buffer.alloc(32, 7).toString("base64"));
+    try {
+      const { userId } = await h.seedUser("kms-session@example.com", "pw-long-enough");
+      const cbs = createSessionCallbacks({ db: stack.db });
+      const sid = await cbs.sessionCreator(
+        { id: userId, tenantId: TENANT, roles: ["User"] },
+        { ip: "203.0.113.7", userAgent: "TestBrowser/1.0" },
+      );
+
+      const stored = await selectMany<{ ip: string | null; userAgent: string | null }>(
+        stack.db,
+        userSessionTable,
+        { id: sid },
+      );
+      expect(isPiiCiphertext(stored[0]?.ip)).toBe(true);
+      expect(isPiiCiphertext(stored[0]?.userAgent)).toBe(true);
+
+      // Login (bidx-Lookup auf verschluesselter user.email) + mine ueber HTTP:
+      // die manuell erzeugte Session kommt mit Klartext-ip/userAgent zurueck.
+      const login = await h.login("kms-session@example.com", "pw-long-enough");
+      const res = await h.authedPost("/api/query", login.token, {
+        type: SessionQueries.mine,
+        payload: {},
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as {
+        data: Array<{ id: string; ip: string | null; userAgent: string | null }>;
+      };
+      const manual = body.data.find((s) => s.id === sid);
+      expect(manual?.ip).toBe("203.0.113.7");
+      expect(manual?.userAgent).toBe("TestBrowser/1.0");
+    } finally {
+      resetPiiSubjectKmsForTests();
+      resetBlindIndexKeyForTests();
+    }
+  });
+});

package/src/sessions/feature.ts

@@ -90,6 +90,8 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     // which are direct-write stores too.
     r.unmanagedTable(buildEntityTableMeta("user-session", userSessionEntity), {
       reason: "read_side.user_sessions_direct_write",
+      // sessionCreator encrypts ip/userAgent via encryptForDirectWrite (#820).
+      piiEncryptedOnWrite: true,
     });
 
     const handlers = {

package/src/sessions/handlers/list.query.ts

@@ -1,6 +1,7 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { decryptStoredPii } from "../../shared";
 import { userSessionTable } from "../schema/user-session";
 
 // Admin view of every session in the active tenant. ctx.db (TenantDb)
@@ -22,14 +23,16 @@ export const listQuery = defineQueryHandler({
     }>(ctx.db, userSessionTable, undefined, {
       orderBy: { col: "createdAt", direction: "desc" },
     });
-    return rows.map((r) => ({
-      id: r.id,
-      userId: r.userId,
-      createdAt: r.createdAt,
-      expiresAt: r.expiresAt,
-      revokedAt: r.revokedAt,
-      ip: r.ip,
-      userAgent: r.userAgent,
-    }));
+    return 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, "sessions:list") : r.ip,
+        userAgent: r.userAgent ? await decryptStoredPii(r.userAgent, "sessions:list") : r.userAgent,
+      })),
+    );
   },
 });

package/src/sessions/handlers/mine.query.ts

@@ -1,6 +1,7 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { decryptStoredPii } from "../../shared";
 import { userSessionTable } from "../schema/user-session";
 
 // "My live sessions" — the backing data for a devices/sessions UI. Returns
@@ -26,13 +27,15 @@ export const mineQuery = defineQueryHandler({
       },
     );
     const currentSid = query.user.sid;
-    return rows.map((r) => ({
-      id: r.id,
-      createdAt: r.createdAt,
-      expiresAt: r.expiresAt,
-      ip: r.ip,
-      userAgent: r.userAgent,
-      current: currentSid === r.id,
-    }));
+    return Promise.all(
+      rows.map(async (r) => ({
+        id: r.id,
+        createdAt: r.createdAt,
+        expiresAt: r.expiresAt,
+        ip: r.ip ? await decryptStoredPii(r.ip, "sessions:mine") : r.ip,
+        userAgent: r.userAgent ? await decryptStoredPii(r.userAgent, "sessions:mine") : r.userAgent,
+        current: currentSid === r.id,
+      })),
+    );
   },
 });