@cosmicdrift/kumiko-bundled-features 0.210.0 → 0.212.0

package/src/jobs/job-run-logger.ts

@@ -67,6 +67,35 @@ async function encryptStartedPayload(
   );
 }
 
+// Same per-subject encryption as encryptStartedPayload, applied to each
+// batched log line's `message` (#2247) before insertMany into
+// jobRunLogsTable — that table is unmanaged/direct-write, so there is no
+// event-piiFields catalog to lean on here either. "message" is the AAD
+// field name and must match the field passed to decryptStoredPii on read
+// (detail.query.ts) or decrypt fails loud. Same skip rules as the payload:
+// null subject (system/cron runs) and absent KMS (rollout mode) both stay
+// plaintext.
+async function encryptLogMessages<T extends { readonly message: string }>(
+  logs: readonly T[],
+  triggeredById: string | null,
+): Promise<T[]> {
+  if (triggeredById === null) return [...logs];
+  const kms = configuredPiiSubjectKms();
+  if (!kms) return [...logs];
+  return Promise.all(
+    logs.map(async (log) => ({
+      ...log,
+      message: await encryptPiiValueForSubject(
+        kms,
+        { kind: "user", userId: triggeredById },
+        log.message,
+        { requestId: "jobs:job-run-logger" },
+        "message",
+      ),
+    })),
+  );
+}
+
 export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallbacks {
   const { db } = opts;
 
@@ -78,10 +107,17 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
   // Bounded cache (LRU-ish with TTL) — worker-crash between start and
   // complete would otherwise leak entries. DB-lookup recovers evicted
   // entries via bull_job_id on jobRunsTable.
-  type CacheEntry = { readonly runId: string; readonly expiresAt: number };
+  // triggeredById rides along with runId (#2247) — resolved once at start
+  // (or on cache-miss DB fallback) so onJobComplete/-Failed know the log
+  // subject without an extra always-on DB round trip.
+  type CacheEntry = {
+    readonly runId: string;
+    readonly triggeredById: string | null;
+    readonly expiresAt: number;
+  };
   const runIdByBullJobId = new Map<string, CacheEntry>();
 
-  function cachePut(bullJobId: string, runId: string): void {
+  function cachePut(bullJobId: string, runId: string, triggeredById: string | null): void {
     // Enforce max-size BEFORE insert. Map iteration returns insertion
     // order, so dropping the first entry is the oldest.
     if (runIdByBullJobId.size >= DEFAULT_CACHE_MAX_ENTRIES) {
@@ -90,24 +126,32 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
     }
     runIdByBullJobId.set(bullJobId, {
       runId,
+      triggeredById,
       expiresAt: Date.now() + DEFAULT_CACHE_TTL_MS,
     });
   }
 
-  function cacheGet(bullJobId: string): string | undefined {
+  function cacheGet(bullJobId: string): CacheEntry | undefined {
     const entry = runIdByBullJobId.get(bullJobId);
     if (!entry) return undefined;
     if (Date.now() >= entry.expiresAt) {
       runIdByBullJobId.delete(bullJobId); // immediate cleanup on terminal callback
       return undefined;
     }
-    return entry.runId;
+    return entry;
   }
 
-  async function resolveRunId(bullJobId: string): Promise<string | undefined> {
+  async function resolveRun(
+    bullJobId: string,
+  ): Promise<{ readonly runId: string; readonly triggeredById: string | null } | undefined> {
     const cached = cacheGet(bullJobId);
-    if (cached) return cached;
-    const row = await fetchOne<{ id: string | number }>(db, jobRunsTable, { bullJobId });
+    if (cached) return { runId: cached.runId, triggeredById: cached.triggeredById };
+    const row = await fetchOne<{ id: string | number; triggeredById: string | null }>(
+      db,
+      jobRunsTable,
+      { bullJobId },
+    );
+    if (!row) return undefined;
     // buildBaseColumns's signature types `id` as `string | number` because
     // it returns both branches of the idType union. We know this table
     // was built with idType: "uuid" (see job-run-table.ts), so narrowing
@@ -115,15 +159,17 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
     // would overload buildBaseColumns per idType — scoped out of this
     // follow-up as its return type has four branches (with/without
     // softDelete × serial/uuid).
-    const id = row ? String(row.id) : undefined;
-    if (id) cachePut(bullJobId, id);
-    return id;
+    const runId = String(row.id);
+    const triggeredById = row.triggeredById ?? null;
+    cachePut(bullJobId, runId, triggeredById);
+    return { runId, triggeredById };
   }
 
   return {
     onJobStart: async (jobName: string, bullJobId: string, meta: JobMeta) => {
       const runId = generateId();
-      cachePut(bullJobId, runId);
+      const triggeredById = meta.triggeredById ?? null;
+      cachePut(bullJobId, runId, triggeredById);
       // Parse against the registered schema so out-of-dispatcher writes
       // get the same validation guarantee as ctx.appendEvent. A shape
       // drift between feature + logger fails loudly at the source
@@ -133,7 +179,7 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
         bullJobId,
         status: "running",
         payload: meta.payload ?? null,
-        triggeredById: meta.triggeredById ?? null,
+        triggeredById,
         startedAt: Temporal.Now.instant().toString(),
         attempt: meta.attempt ?? 1,
       });
@@ -158,12 +204,13 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
       duration: number,
       logs: JobLogEntry[],
     ) => {
-      const runId = await resolveRunId(bullJobId);
+      const resolved = await resolveRun(bullJobId);
       // skip: state loss between start + complete (worker restart, cache
       // evicted AND DB has no matching bull_job_id). Rare edge case; we
       // drop the completion write rather than forging a run row from
       // scratch — forensics still has the original BullMQ lifecycle.
-      if (!runId) return;
+      if (!resolved) return;
+      const { runId, triggeredById } = resolved;
       const payload = runCompletedSchema.parse({
         duration,
         finishedAt: Temporal.Now.instant().toString(),
@@ -188,10 +235,11 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
       // skip: empty log batch — the worker ran silent. No child rows to
       // insert; the status update above already recorded completion.
       if (payload.logs.length > 0) {
+        const encryptedLogs = await encryptLogMessages(payload.logs, triggeredById);
         await insertMany(
           db,
           jobRunLogsTable,
-          payload.logs.map((log) => ({
+          encryptedLogs.map((log) => ({
             runId,
             level: log.level,
             message: log.message,
@@ -208,10 +256,11 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
       error: string,
       logs: JobLogEntry[],
     ) => {
-      const runId = await resolveRunId(bullJobId);
+      const resolved = await resolveRun(bullJobId);
       // skip: same rare state-loss case as in onJobComplete — drop the
       // failure write rather than forge a run row from scratch.
-      if (!runId) return;
+      if (!resolved) return;
+      const { runId, triggeredById } = resolved;
       // Read started_at off the row so we can compute duration
       // symmetrically to onJobComplete (which gets duration from the
       // worker). The row already has started_at from onJobStart.
@@ -243,10 +292,11 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
       );
       // skip: empty log batch — mirror of onJobComplete
       if (payload.logs.length > 0) {
+        const encryptedLogs = await encryptLogMessages(payload.logs, triggeredById);
         await insertMany(
           db,
           jobRunLogsTable,
-          payload.logs.map((log) => ({
+          encryptedLogs.map((log) => ({
             runId,
             level: log.level,
             message: log.message,

package/src/jobs/web/job-run-detail-screen.tsx

@@ -63,6 +63,7 @@ export function JobRunDetailScreen(): ReactNode {
     setState({ kind: "ready", run: res.data });
   }, [dispatcher, runId]);
 
+  // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
   useEffect(() => {
     void load();
   }, [load]);

package/src/page-render/web.ts

@@ -1,3 +1,4 @@
+// kumiko-lint-ignore app-feature-structure Server-side re-export barrel (branding/sanitize helpers), not a client screen — name collision with the web.ts monolith heuristic
 export {
   type BrandingTokens,
   brandingHeaderHtml,

package/src/personal-access-tokens/changes.json

@@ -4,5 +4,12 @@
     "type": "improvement",
     "title": "personal-access-tokens: add `toggleable` option so the whole feature can be tier-gated vi…",
     "detail": "personal-access-tokens: add `toggleable` option so the whole feature can be tier-gated via the tier-engine (mirrors ledger/tags). Pass `{ toggleable: { default: false } }` for fail-closed gating — PAT is then off until a tier lists `\"personal-access-tokens\"` in its features. Omitting the option keeps PAT always-on (no behaviour change for existing consumers)."
+  },
+  {
+    "version": "0.202.0",
+    "type": "breaking",
+    "title": "personal-access-tokens: `write:create` now requires `currentPassword` (+ `mfaCode` if MFA enrolled) (e91d4cb).",
+    "detail": "`personal-access-tokens:write:create` now requires `currentPassword` (verified against the caller's password hash) before minting a token, and rejects when the caller has MFA enrolled and `mfaCode` is missing or wrong — a session cookie alone is no longer enough to stand up a durable API credential. `expiresInDays` now defaults to 90 days instead of never-expiring when omitted (the existing 3650-day cap is unchanged, so a genuinely long-lived token is still possible if requested explicitly). Changing a user's password, or enabling/disabling MFA, now revokes all of that user's live PAT tokens — mirrors the existing session auto-revoke-on-password-change behavior. `run-prod-app`/`run-dev-app` wire the new MFA↔PAT revoke callback automatically when both `auth-mfa` and `personal-access-tokens` are mounted; no app-level change needed for that part.",
+    "migration": "Apps that already mint PATs (their own client code, scripts, or tests) need to add `currentPassword` to the `create` request payload — this is a breaking change to the `create` request shape despite the minor bump (bundled-features doesn't follow strict semver across its handler schemas yet). If the caller has MFA enrolled, also include a valid `mfaCode`."
   }
 ]

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

@@ -149,6 +149,7 @@ export function createPersonalAccessTokensFeature(
     // the app places it via r.nav in its logged-in settings area. dormant:
     // true skips createKumikoApp's missing-client-plugin boot diagnostic
     // (#2025) for apps that don't nav this screen (#2034).
+    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
     r.screen({
       id: PAT_SCREEN_ID,
       type: "custom",

package/src/secrets/__tests__/access-options.integration.test.ts

@@ -0,0 +1,114 @@
+// #2296 — createSecretsFeature() took no options at all: set/delete/list were
+// hard-wired to ["TenantAdmin"], so an app with its own role vocabulary
+// (e.g. ["Admin","Editor"]) could not let its own admins manage secrets
+// without also granting the framework "TenantAdmin" role — the same
+// Role-Naming-Drift documented on custom-fields' valueWriteRoles. Verifies
+// the new `roles`/`access` options actually gate set/delete/list, that the
+// framework-default role loses access once overridden, and that `openToAll`
+// really does open the surface to any authenticated tenant user.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createEnvMasterKeyProvider,
+  type MasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createSecretsFeature } from "../feature";
+import { createSecretsContext } from "../secrets-context";
+import { tenantSecretsTable } from "../table";
+
+function masterKeyProvider(): MasterKeyProvider {
+  return createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+}
+
+async function buildStack(feature: ReturnType<typeof createSecretsFeature>): Promise<TestStack> {
+  const provider = masterKeyProvider();
+  const stack = await setupTestStack({
+    features: [feature],
+    extraContext: ({ db }) => ({
+      secrets: createSecretsContext({ db, masterKeyProvider: provider }),
+    }),
+  });
+  await unsafePushTables(stack.db, { tenant_secrets: tenantSecretsTable });
+  await createEventsTable(stack.db);
+  return stack;
+}
+
+const admin = createTestUser({ roles: ["TenantAdmin"] });
+const customRoleUser = createTestUser({ roles: ["Admin"] });
+const unprivileged = createTestUser({ roles: ["Viewer"] });
+
+describe("secrets — roles option (#2296)", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await buildStack(createSecretsFeature({ roles: ["Admin"] }));
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("a custom-role user can set, list and delete", async () => {
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: "api.key.role-opt", value: "shh" },
+      customRoleUser,
+    );
+    const list = await stack.http.queryOk<Array<{ key: string }>>(
+      "secrets:query:list",
+      {},
+      customRoleUser,
+    );
+    expect(list.some((r) => r.key === "api.key.role-opt")).toBe(true);
+    await stack.http.writeOk("secrets:write:delete", { key: "api.key.role-opt" }, customRoleUser);
+  });
+
+  test("the framework-default TenantAdmin role is denied once `roles` overrides it", async () => {
+    const denied = await stack.http.writeErr(
+      "secrets:write:set",
+      { key: "api.key.denied", value: "x" },
+      admin,
+    );
+    expect(denied.code).toBe("access_denied");
+  });
+});
+
+describe("secrets — access: { openToAll: true } (#2296)", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await buildStack(createSecretsFeature({ access: { openToAll: true } }));
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("any authenticated tenant user can set, list and delete", async () => {
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: "api.key.open", value: "shh" },
+      unprivileged,
+    );
+    const list = await stack.http.queryOk<Array<{ key: string }>>(
+      "secrets:query:list",
+      {},
+      unprivileged,
+    );
+    expect(list.some((r) => r.key === "api.key.open")).toBe(true);
+    await stack.http.writeOk("secrets:write:delete", { key: "api.key.open" }, unprivileged);
+  });
+});

package/src/secrets/constants.ts

@@ -0,0 +1,12 @@
+// @runtime client
+// secrets bundle constants — default RBAC for set/delete/list (#2296).
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+// Default-RBAC of the set/delete/list handlers, hard-wired to ["TenantAdmin"]
+// before #2296. Apps with their own role vocabulary override via
+// createSecretsFeature({ roles }) or createSecretsFeature({ access }) — the
+// rotate job stays untouched, it's a manual/ops path across all tenants by
+// design, not a per-tenant RBAC surface.
+export const DEFAULT_SECRETS_ROLES = ["TenantAdmin"] as const;
+export const DEFAULT_SECRETS_ACCESS: AccessRule = { roles: DEFAULT_SECRETS_ROLES };

package/src/secrets/feature.ts

@@ -1,11 +1,16 @@
-import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type AccessRule,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { z } from "zod";
-import { deleteWrite } from "./handlers/delete.write";
-import { listQuery } from "./handlers/list.query";
+import { DEFAULT_SECRETS_ACCESS } from "./constants";
+import { createDeleteHandler } from "./handlers/delete.write";
+import { createListHandler } from "./handlers/list.query";
 import { rotateJob } from "./handlers/rotate.job";
-import { setWrite } from "./handlers/set.write";
+import { createSetHandler } from "./handlers/set.write";
 import { secretReadSchema } from "./secrets-context";
 import { tenantSecretEntity, tenantSecretsTable } from "./table";
 
@@ -84,10 +89,31 @@ export function requireSecretsContext(
   };
 }
 
-export function createSecretsFeature(): FeatureDefinition {
+export type SecretsFeatureOptions = {
+  /** Access rule for the `set`, `delete` and `list` handlers. Default
+   *  { roles: ["TenantAdmin"] }. Adopt the host's role vocabulary with
+   *  { roles: [...] }, or { openToAll: true } to let any authenticated tenant
+   *  user manage secrets — note this is a much larger blast radius than the
+   *  default: tenant credentials (API keys, tokens) become writable/deletable,
+   *  and their previews/hints listable, by every tenant member, not just
+   *  admins. Takes precedence over `roles`. The `rotate` job is unaffected —
+   *  it's a manual, cross-tenant ops path, not per-tenant RBAC. */
+  readonly access?: AccessRule;
+  /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
+  readonly roles?: readonly string[];
+};
+
+function resolveSecretsAccess(opts: SecretsFeatureOptions): AccessRule {
+  if (opts.access !== undefined) return opts.access;
+  if (opts.roles !== undefined) return { roles: opts.roles };
+  return DEFAULT_SECRETS_ACCESS;
+}
+
+export function createSecretsFeature(opts: SecretsFeatureOptions = {}): FeatureDefinition {
+  const access = resolveSecretsAccess(opts);
   return defineFeature(SECRETS_FEATURE_NAME, (r) => {
     r.describe(
-      "Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump.",
+      'Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: ["TenantAdmin"] }; adopt the host\'s role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: true } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins).',
     );
     r.uiHints({
       displayLabel: "Tenant Secrets",
@@ -117,9 +143,9 @@ export function createSecretsFeature(): FeatureDefinition {
     // The rotation job deliberately reaches for ctx.db as DbConnection
     // (raw, cross-tenant) because rotation is a deployment-wide operation —
     // no feature-wide r.systemScope() needed.
-    r.writeHandler(setWrite);
-    r.writeHandler(deleteWrite);
-    r.queryHandler(listQuery);
+    r.writeHandler(createSetHandler(access));
+    r.writeHandler(createDeleteHandler(access));
+    r.queryHandler(createListHandler(access));
     // Manual-only by design: ops triggers rotation after a KEK version flip.
     // BullMQ delivers to exactly one worker, so running it against a busy
     // table on multiple instances is still safe.

package/src/secrets/handlers/delete.write.ts

@@ -1,20 +1,27 @@
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { type AccessRule, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
+import { DEFAULT_SECRETS_ACCESS } from "../constants";
 import { requireSecretsContext } from "../feature";
 
-export const deleteWrite = defineWriteHandler({
-  name: "delete",
-  schema: z.object({
-    key: z.string().min(1).max(100),
-  }),
-  access: { roles: ["TenantAdmin"] },
-  handler: async (event, ctx) => {
-    const secrets = requireSecretsContext(ctx, "secrets:write:delete");
-    const removed = await secrets.delete(event.user.tenantId, event.payload.key, {
-      deletedBy: event.user.id,
-    });
-    if (!removed) return failNotFound("tenant-secret", event.payload.key);
-    return { isSuccess: true, data: { key: event.payload.key } };
-  },
-});
+export function createDeleteHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
+  return defineWriteHandler({
+    name: "delete",
+    schema: z.object({
+      key: z.string().min(1).max(100),
+    }),
+    access,
+    handler: async (event, ctx) => {
+      const secrets = requireSecretsContext(ctx, "secrets:write:delete");
+      const removed = await secrets.delete(event.user.tenantId, event.payload.key, {
+        deletedBy: event.user.id,
+      });
+      if (!removed) return failNotFound("tenant-secret", event.payload.key);
+      return { isSuccess: true, data: { key: event.payload.key } };
+    },
+  });
+}
+
+// Backwards-compat: existing imports of `deleteWrite` keep working —
+// identical to createDeleteHandler() with the default access.
+export const deleteWrite = createDeleteHandler();

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

@@ -1,37 +1,44 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { type AccessRule, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { DEFAULT_SECRETS_ACCESS } from "../constants";
 import { tenantSecretsTable } from "../table";
 
 // Lists all secrets for the current tenant. Returns redactedPreview, never
 // the plaintext. Decryption would be pointless here anyway — this is the
 // TenantAdmin UI, not feature code that needs the value.
-export const listQuery = defineQueryHandler({
-  name: "list",
-  schema: z.object({}),
-  access: { roles: ["TenantAdmin"] },
-  handler: async (event, ctx) => {
-    const rows = await selectMany<{
-      key: string;
-      kekVersion: number;
-      metadata: { redactedPreview?: string; hint?: string };
-      lastRotatedAt: unknown;
-      insertedAt: unknown;
-    }>(
-      ctx.db.raw,
-      tenantSecretsTable,
-      { tenantId: event.user.tenantId },
-      {
-        orderBy: { col: "key", direction: "asc" },
-      },
-    );
-    return rows.map((r) => ({
-      key: r.key,
-      redactedPreview: r.metadata.redactedPreview ?? null,
-      hint: r.metadata.hint ?? null,
-      kekVersion: r.kekVersion,
-      lastRotatedAt: r.lastRotatedAt,
-      createdAt: r.insertedAt,
-    }));
-  },
-});
+export function createListHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
+  return defineQueryHandler({
+    name: "list",
+    schema: z.object({}),
+    access,
+    handler: async (event, ctx) => {
+      const rows = await selectMany<{
+        key: string;
+        kekVersion: number;
+        metadata: { redactedPreview?: string; hint?: string };
+        lastRotatedAt: unknown;
+        insertedAt: unknown;
+      }>(
+        ctx.db.raw,
+        tenantSecretsTable,
+        { tenantId: event.user.tenantId },
+        {
+          orderBy: { col: "key", direction: "asc" },
+        },
+      );
+      return rows.map((r) => ({
+        key: r.key,
+        redactedPreview: r.metadata.redactedPreview ?? null,
+        hint: r.metadata.hint ?? null,
+        kekVersion: r.kekVersion,
+        lastRotatedAt: r.lastRotatedAt,
+        createdAt: r.insertedAt,
+      }));
+    },
+  });
+}
+
+// Backwards-compat: existing imports of `listQuery` keep working — identical
+// to createListHandler() with the default access.
+export const listQuery = createListHandler();

package/src/secrets/handlers/set.write.ts

@@ -1,45 +1,52 @@
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { type AccessRule, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { DEFAULT_SECRETS_ACCESS } from "../constants";
 import { requireSecretsContext } from "../feature";
 
-export const setWrite = defineWriteHandler({
-  name: "set",
-  schema: z.object({
-    key: z.string().min(1).max(100),
-    value: z.string(),
-    // Optional fixed-length preview — if the caller's UI wants a domain-
-    // specific redaction ("sk_live_abc…xyz") it can send it here; else the
-    // handler derives a generic one (first-3-chars + bullets).
-    redactedPreview: z.string().max(50).optional(),
-    hint: z.string().max(200).optional(),
-  }),
-  access: { roles: ["TenantAdmin"] },
-  handler: async (event, ctx) => {
-    const secrets = requireSecretsContext(ctx, "secrets:write:set");
-    const { key, value, redactedPreview, hint } = event.payload;
+export function createSetHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
+  return defineWriteHandler({
+    name: "set",
+    schema: z.object({
+      key: z.string().min(1).max(100),
+      value: z.string(),
+      // Optional fixed-length preview — if the caller's UI wants a domain-
+      // specific redaction ("sk_live_abc…xyz") it can send it here; else the
+      // handler derives a generic one (first-3-chars + bullets).
+      redactedPreview: z.string().max(50).optional(),
+      hint: z.string().max(200).optional(),
+    }),
+    access,
+    handler: async (event, ctx) => {
+      const secrets = requireSecretsContext(ctx, "secrets:write:set");
+      const { key, value, redactedPreview, hint } = event.payload;
 
-    // Preview-priority: explicit payload param > feature-declared redact
-    // (via r.secret()) > generic default. A feature that declared a
-    // domain-aware redact (Stripe keys: "sk_test...2345") wins over the
-    // framework default unless the caller sent a specific preview.
-    const keyDef = ctx.registry.getSecretKey(key);
-    const featureRedact = keyDef?.redact;
-    const redactFn: (v: string) => string = redactedPreview
-      ? () => redactedPreview
-      : (featureRedact ?? defaultRedact);
+      // Preview-priority: explicit payload param > feature-declared redact
+      // (via r.secret()) > generic default. A feature that declared a
+      // domain-aware redact (Stripe keys: "sk_test...2345") wins over the
+      // framework default unless the caller sent a specific preview.
+      const keyDef = ctx.registry.getSecretKey(key);
+      const featureRedact = keyDef?.redact;
+      const redactFn: (v: string) => string = redactedPreview
+        ? () => redactedPreview
+        : (featureRedact ?? defaultRedact);
 
-    await secrets.set(event.user.tenantId, key, value, {
-      redact: redactFn,
-      ...(hint ? { hint } : {}),
-      updatedBy: event.user.id,
-    });
+      await secrets.set(event.user.tenantId, key, value, {
+        redact: redactFn,
+        ...(hint ? { hint } : {}),
+        updatedBy: event.user.id,
+      });
 
-    return {
-      isSuccess: true,
-      data: { key, redactedPreview: redactedPreview ?? redactFn(value) },
-    };
-  },
-});
+      return {
+        isSuccess: true,
+        data: { key, redactedPreview: redactedPreview ?? redactFn(value) },
+      };
+    },
+  });
+}
+
+// Backwards-compat: existing imports of `setWrite` keep working — identical
+// to createSetHandler() with the default access.
+export const setWrite = createSetHandler();
 
 // Fallback redaction: show at most the first 3 chars + trailing bullets.
 // Deliberately conservative — a too-generous preview defeats the point.

package/src/secrets/index.ts

@@ -1,3 +1,4 @@
+export { DEFAULT_SECRETS_ACCESS, DEFAULT_SECRETS_ROLES } from "./constants";
 export {
   createSecretsContext,
   createSecretsFeature,
@@ -5,14 +6,18 @@ export {
   SECRETS_FEATURE_NAME,
   type SecretsContext,
   type SecretsContextOptions,
+  type SecretsFeatureOptions,
   type StoredEnvelope,
   type StoredMetadata,
   secretsEnvSchema,
   TENANT_SECRET_READ_EVENT,
   tenantSecretsTable,
 } from "./feature";
+export { createDeleteHandler, deleteWrite } from "./handlers/delete.write";
+export { createListHandler, listQuery } from "./handlers/list.query";
 export {
   type RotateJobPayload,
   type RotateJobResult,
   rotateJob,
 } from "./handlers/rotate.job";
+export { createSetHandler, setWrite } from "./handlers/set.write";