@cosmicdrift/kumiko-samples 0.368.0 → 0.370.0

package/packages/bundled-features/src/personal-access-tokens/resolver.ts

@@ -2,11 +2,11 @@ import type { TokenVerifier } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { isExpiredAt } from "./expiry.js";
-import { hashPatToken } from "./hash.js";
-import { resolvePatRoles } from "./roles.js";
-import { apiTokenTable } from "./schema/api-token.js";
-import { expandScopes, type PatScopeConfig } from "./scopes.js";
+import { isExpiredAt } from "./expiry.ts";
+import { hashPatToken } from "./hash.ts";
+import { resolvePatRoles } from "./roles.ts";
+import { apiTokenTable } from "./schema/api-token.ts";
+import { expandScopes, type PatScopeConfig } from "./scopes.ts";
 
 // Hot-path resolver — raw-DB like session-callbacks (a dispatcher roundtrip on
 // every request buys nothing here). Hash the bearer token, point-read the row,

package/packages/bundled-features/src/personal-access-tokens/revoke-for-user.ts

@@ -12,8 +12,8 @@ import {
   PAT_REVOKED_AGGREGATE_TYPE,
   PAT_REVOKED_EVENT_QN,
   patRevokedSchema,
-} from "./pat-revoked-event.js";
-import { apiTokenTable } from "./schema/api-token.js";
+} from "./pat-revoked-event.ts";
+import { apiTokenTable } from "./schema/api-token.ts";
 
 // Cross-tenant revoke: password-change and MFA-enable/disable are account-
 // level security events, not scoped to one tenant. Mirrors sessions'

package/packages/bundled-features/src/personal-access-tokens/roles.ts

@@ -2,8 +2,8 @@ import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { buildSessionRoles } from "@cosmicdrift/kumiko-framework/engine";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
-import { tenantMembershipsTable } from "../tenant/index.js";
-import { isPrincipalRowBlocked, type UserStatus, userTable } from "../user/index.js";
+import { tenantMembershipsTable } from "../tenant/index.ts";
+import { isPrincipalRowBlocked, type UserStatus, userTable } from "../user/index.ts";
 
 // Live role resolution for a (userId, tenantId), mirroring login.write.ts:
 // global roles (users.roles) ∪ tenant-membership roles (forbidden roles

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

@@ -5,7 +5,7 @@ import {
   createTextField,
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { API_TOKEN_ENTITY_NAME } from "../constants.js";
+import { API_TOKEN_ENTITY_NAME } from "../constants.ts";
 
 // One row per Personal Access Token. Like store_user_sessions this is a
 // direct-write store (r.unmanagedTable): the create/revoke handlers write it and

package/packages/bundled-features/src/personal-access-tokens/screens.ts

@@ -12,8 +12,8 @@ import {
   PAT_SCREEN_ID,
   PatHandlers,
   PatQueries,
-} from "./constants.js";
-import type { PatScopeConfig } from "./scopes.js";
+} from "./constants.ts";
+import type { PatScopeConfig } from "./scopes.ts";
 
 const PAT_STATUS_OPTION_KEY_PREFIX = "pat.list.status.";
 // Same keys the mint form's `scopes` multiSelect options resolve through

package/packages/bundled-features/src/presets/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "securityBaselineFeatures and dsgvoSelfServiceFeatures are deprecated",
+    "detail": "Both presets stay for one release. Replace securityBaselineFeatures({ includeSessions }) with composeSecurityStack({ includeSessions }) and dsgvoSelfServiceFeatures({ userDataRights }) with composeGdprStack({ selfService: { userDataRights } }), both from @cosmicdrift/kumiko-dev-server/compose-stacks. The stacks mount the same features in the same order."
+  },
   {
     "version": "0.262.0",
     "type": "improvement",

package/packages/bundled-features/src/presets/dsgvo-self-service.ts

@@ -1,12 +1,12 @@
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { createComplianceProfilesFeature } from "../compliance-profiles/index.js";
-import { createDataRetentionFeature } from "../data-retention/index.js";
-import { createSessionsFeature } from "../sessions/index.js";
+import { createComplianceProfilesFeature } from "../compliance-profiles/index.ts";
+import { createDataRetentionFeature } from "../data-retention/index.ts";
+import { createSessionsFeature } from "../sessions/index.ts";
 import {
   createUserDataRightsFeature,
   type UserDataRightsOptions,
-} from "../user-data-rights/index.js";
-import { createUserProfileFeature } from "../user-profile/index.js";
+} from "../user-data-rights/index.ts";
+import { createUserProfileFeature } from "../user-profile/index.ts";
 
 export type DsgvoSelfServiceOptions = {
   /** Passed through to createUserDataRightsFeature — export/deletion mail
@@ -22,6 +22,8 @@ export type DsgvoSelfServiceOptions = {
 // comment. text-content + legal-pages stay out deliberately — legal-pages
 // has an app-specific wrapLayout, text-content is a standalone foundation;
 // both are spread in by the app itself.
+/** @deprecated Removed in the next release. Use `composeGdprStack({ selfService: { userDataRights } })`
+ *  from `@cosmicdrift/kumiko-dev-server/compose-stacks`. */
 export function dsgvoSelfServiceFeatures(opts: DsgvoSelfServiceOptions = {}): FeatureDefinition[] {
   return [
     createDataRetentionFeature(),

package/packages/bundled-features/src/presets/index.ts

@@ -1,2 +1,2 @@
-export { type DsgvoSelfServiceOptions, dsgvoSelfServiceFeatures } from "./dsgvo-self-service.js";
-export { type SecurityBaselineOptions, securityBaselineFeatures } from "./security-baseline.js";
+export { type DsgvoSelfServiceOptions, dsgvoSelfServiceFeatures } from "./dsgvo-self-service.ts";
+export { type SecurityBaselineOptions, securityBaselineFeatures } from "./security-baseline.ts";

package/packages/bundled-features/src/presets/security-baseline.ts

@@ -1,14 +1,16 @@
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { createAuditFeature } from "../audit/index.js";
-import { createCryptoShreddingFeature } from "../crypto-shredding/index.js";
-import { createRateLimitingFeature } from "../rate-limiting/index.js";
-import { createSessionsFeature } from "../sessions/index.js";
+import { createAuditFeature } from "../audit/index.ts";
+import { createCryptoShreddingFeature } from "../crypto-shredding/index.ts";
+import { createRateLimitingFeature } from "../rate-limiting/index.ts";
+import { createSessionsFeature } from "../sessions/index.ts";
 
 export type SecurityBaselineOptions = {
   readonly includeSessions?: boolean;
 };
 
 // Host app must mount user, tenant, auth-foundation (sessions/audit requires).
+/** @deprecated Removed in the next release. Use `composeSecurityStack({ includeSessions })`
+ *  from `@cosmicdrift/kumiko-dev-server/compose-stacks`. */
 export function securityBaselineFeatures(opts: SecurityBaselineOptions = {}): FeatureDefinition[] {
   return [
     ...(opts.includeSessions !== false ? [createSessionsFeature()] : []),

package/packages/bundled-features/src/rate-limiting/feature.ts

@@ -1,6 +1,6 @@
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { rateLimitStatus } from "./handlers/status.query.js";
-import { RATE_LIMITING_I18N } from "./i18n.js";
+import { rateLimitStatus } from "./handlers/status.query.ts";
+import { RATE_LIMITING_I18N } from "./i18n.ts";
 
 // Opt-in feature. Loading it does NOT install rate-limit middleware —
 // the framework auto-wires the L3 dispatcher hook and the resolver

package/packages/bundled-features/src/rate-limiting/handlers/bucket-access.ts

@@ -1,7 +1,7 @@
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import type { RateLimitPer, SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
-import { RateLimitErrors } from "../constants.js";
+import { RateLimitErrors } from "../constants.ts";
 
 // Bucket keys are `<dimension>:<subject>[:<handler>]` (framework
 // rate-limit/bucket.ts) — only `tenant*` and `user*` carry a subject the

package/packages/bundled-features/src/rate-limiting/handlers/status.query.ts

@@ -1,8 +1,8 @@
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { RateLimitErrors } from "../constants.js";
-import { bucketAccessDenied } from "./bucket-access.js";
+import { RateLimitErrors } from "../constants.ts";
+import { bucketAccessDenied } from "./bucket-access.ts";
 
 // Ops-side bucket inspection. Pass the bucket key (e.g. "user:42",
 // "user+handler:42:orders:write:order:create") plus the limit/window the bucket

package/packages/bundled-features/src/rate-limiting/index.ts

@@ -1,2 +1,2 @@
-export { RATE_LIMITING_FEATURE, RateLimitErrors, RateLimitQueries } from "./constants.js";
-export { createRateLimitingFeature } from "./feature.js";
+export { RATE_LIMITING_FEATURE, RateLimitErrors, RateLimitQueries } from "./constants.ts";
+export { createRateLimitingFeature } from "./feature.ts";

package/packages/bundled-features/src/readiness/changes.json

@@ -1 +1,10 @@
-[]
+[
+  {
+    "version": "0.370.0",
+    "type": "breaking",
+    "title": "The deprecated readinessFeature constant is removed",
+    "detail": "readinessFeature was kept next to createReadinessFeature() for one release. Mount the feature by calling createReadinessFeature().",
+    "migration": "Run bun kumiko-upgrade --apply. It replaces readinessFeature with createReadinessFeature().",
+    "codemod": "scripts/codemod/feature-factory.ts"
+  }
+]

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

@@ -9,7 +9,7 @@
 // `ready` boolean — the settings-checklist call for admin UIs.
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { statusQuery } from "./handlers/status.query.js";
+import { statusQuery } from "./handlers/status.query.ts";
 
 export function createReadinessFeature() {
   return defineFeature(
@@ -35,6 +35,3 @@ export function createReadinessFeature() {
     { dedupeOptions: {} },
   );
 }
-
-/** @deprecated Use createReadinessFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
-export const readinessFeature = createReadinessFeature();

package/packages/bundled-features/src/readiness/handlers/status.query.ts

@@ -5,7 +5,7 @@ import {
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { ReadinessQueries } from "../constants.js";
+import { ReadinessQueries } from "../constants.ts";
 
 export type ReadinessMissingSecret = { readonly key: string };
 

package/packages/bundled-features/src/readiness/index.ts

@@ -1,3 +1,3 @@
-export { READINESS_FEATURE, ReadinessQueries } from "./constants.js";
-export { createReadinessFeature, readinessFeature } from "./feature.js";
-export type { ReadinessMissingSecret } from "./handlers/status.query.js";
+export { READINESS_FEATURE, ReadinessQueries } from "./constants.ts";
+export { createReadinessFeature } from "./feature.ts";
+export type { ReadinessMissingSecret } from "./handlers/status.query.ts";

package/packages/bundled-features/src/renderer-foundation/api.ts

@@ -5,8 +5,8 @@
 
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
-import { DEFAULT_PLUGIN_BY_KIND, type RenderKind } from "./constants.js";
-import { RendererError, type RendererPlugin } from "./types.js";
+import { DEFAULT_PLUGIN_BY_KIND, type RenderKind } from "./constants.ts";
+import { RendererError, type RendererPlugin } from "./types.ts";
 
 export type RendererFoundationApi = {
   /**

package/packages/bundled-features/src/renderer-foundation/constants.ts

@@ -2,7 +2,7 @@
 // bundles share the enum so plugins (@cosmicdrift/kumiko-renderer-mail-html etc.)
 // do not have to import two sources. Cross-feature imports go
 // through the barrel (../template-resolver), not via deep import.
-import type { RenderKind as RenderKindLocal } from "../template-resolver/index.js";
+import type { RenderKind as RenderKindLocal } from "../template-resolver/index.ts";
 
 // Extension-point name for renderer plugins (@cosmicdrift/kumiko-renderer-mail-html, @cosmicdrift/kumiko-renderer-puppeteer-client, ...).
 export const RENDERER_EXTENSION = "renderer" as const;
@@ -12,7 +12,7 @@ export {
   type ContentFormat,
   RENDER_KINDS,
   type RenderKind,
-} from "../template-resolver/index.js";
+} from "../template-resolver/index.ts";
 
 // Standard-Default-Plugin pro Kind, wenn Tenant keine explizite Config
 // gesetzt hat. App-Bootstrap kann das via TenantConfigKey überschreiben.

package/packages/bundled-features/src/renderer-foundation/feature.ts

@@ -1,6 +1,6 @@
 import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
-import { RENDERER_EXTENSION } from "./constants.js";
-import { isRendererRegistrationPlugin, type RendererPlugin } from "./types.js";
+import { RENDERER_EXTENSION } from "./constants.ts";
+import { isRendererRegistrationPlugin, type RendererPlugin } from "./types.ts";
 
 // renderer-foundation — plugin foundation for renderers (HTML mail, PDF,
 // image). Plan doc:

package/packages/bundled-features/src/renderer-foundation/index.ts

@@ -1,9 +1,9 @@
-export { attachmentFileNameSchema } from "../shared/index.js";
+export { attachmentFileNameSchema } from "../shared/index.ts";
 export {
   createRendererFoundationApi,
   type RendererFoundationApi,
   requireRendererFoundation,
-} from "./api.js";
+} from "./api.ts";
 export {
   CONTENT_FORMATS,
   type ContentFormat,
@@ -11,8 +11,8 @@ export {
   RENDER_KINDS,
   RENDERER_EXTENSION,
   type RenderKind,
-} from "./constants.js";
-export { collectRendererPlugins, createRendererFoundationFeature } from "./feature.js";
+} from "./constants.ts";
+export { collectRendererPlugins, createRendererFoundationFeature } from "./feature.ts";
 export {
   type DocumentPayload,
   type DocumentPdfDraft,
@@ -24,6 +24,9 @@ export {
   type InlineAttachmentRef,
   isRendererRegistrationPlugin,
   type MailAttachmentRef,
+  type MailChrome,
+  type MailChromeLink,
+  type MailChromeRequest,
   type MailDraft,
   type MailPayload,
   type PdfOptions,
@@ -36,4 +39,4 @@ export {
   type RenderProvenance,
   type RenderRequest,
   type RenderResponse,
-} from "./types.js";
+} from "./types.ts";

package/packages/bundled-features/src/renderer-foundation/types.ts

@@ -7,8 +7,8 @@ import type {
   PdfPageFormat,
   PdfTemplateMeta,
   TemplateScope,
-} from "../template-resolver/index.js";
-import { type ContentFormat, RENDERER_EXTENSION, type RenderKind } from "./constants.js";
+} from "../template-resolver/index.ts";
+import { type ContentFormat, RENDERER_EXTENSION, type RenderKind } from "./constants.ts";
 
 // RenderRequest — Plugins erhalten das. Resource-Mode wählt der Caller
 // (renderer-foundation api) je nach kind oder explizit. Plugin selbst
@@ -189,12 +189,32 @@ export type RendererContext = {
 // - Domain failures throw `RendererError`, not a bare Error.
 // - `ctx` is required; plugins without service deps ignore it. Function-arg
 //   variance still lets `(req) => ...` implementations satisfy the contract.
+export type MailChromeLink = { readonly label: string; readonly url: string };
+
+/** The tenant's mail look with every text resolved for one locale, for pages a
+ *  recipient reaches from a mail link. URLs are http(s) only, the logo https only,
+ *  the accent color a #rrggbb hex. */
+export type MailChrome = {
+  readonly tenantName: string;
+  readonly brandSuffix: string;
+  readonly logoUrl?: string;
+  readonly accentColor?: string;
+  readonly siteUrl?: string;
+  readonly footerText?: string;
+  readonly imprint?: MailChromeLink;
+  readonly privacy?: MailChromeLink;
+};
+
+export type MailChromeRequest = { readonly locale: string };
+
 export type RendererPlugin = {
   readonly name: string;
   readonly kinds: ReadonlyArray<RenderKind>;
   render(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
   /** Optional: plugins that print documents offer a preview that never reaches the print service. */
   previewDocument?(req: DocumentPreviewRequest, ctx: RendererContext): Promise<DocumentPreview>;
+  /** Optional: mail plugins hand out their brand row and footer for pages outside a mail. */
+  readMailChrome?(req: MailChromeRequest, ctx: RendererContext): Promise<MailChrome>;
 };
 
 export class RendererError extends Error {

package/packages/bundled-features/src/renderer-pdf/feature.ts

@@ -4,8 +4,8 @@ import {
   RendererError,
   type RenderRequest,
   type RenderResponse,
-} from "../renderer-foundation/index.js";
-import { pdfTableDocumentSchema, renderTablePdf } from "./render-table-pdf.js";
+} from "../renderer-foundation/index.ts";
+import { pdfTableDocumentSchema, renderTablePdf } from "./render-table-pdf.ts";
 
 export async function renderTablePdfRequest(req: RenderRequest): Promise<RenderResponse> {
   if (req.kind !== "document-pdf") {

package/packages/bundled-features/src/renderer-pdf/index.ts

@@ -1,4 +1,4 @@
-export { createRendererPdfFeature } from "./feature.js";
+export { createRendererPdfFeature } from "./feature.ts";
 export {
   type PdfTableColumn,
   type PdfTableDocument,
@@ -6,4 +6,4 @@ export {
   type PdfTableResult,
   pdfTableDocumentSchema,
   renderTablePdf,
-} from "./render-table-pdf.js";
+} from "./render-table-pdf.ts";

package/packages/bundled-features/src/renderer-pdf/render-table-pdf.ts

@@ -1,7 +1,7 @@
 import { PDFDocument, type PDFFont, type PDFPage, rgb, StandardFonts } from "pdf-lib";
 import * as z from "zod";
-import { RendererError } from "../renderer-foundation/index.js";
-import type { PdfPageFormat } from "../template-resolver/index.js";
+import { RendererError } from "../renderer-foundation/index.ts";
+import type { PdfPageFormat } from "../template-resolver/index.ts";
 
 // Upper bounds keep a hostile or runaway payload from exhausting memory and CPU in layout.
 const PDF_TABLE_MAX_ROWS = 10_000;

package/packages/bundled-features/src/secrets/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "createSecretsFeature carries its env schema type",
+    "detail": "createSecretsFeature returns the feature typed with secretsEnvSchema, so composeEnvSchema types the KUMIKO_SECRETS_MASTER_KEY_* variables."
+  },
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "secrets exports SecretsHandlers (set, delete) and SecretsQueries (list) handler names",
+    "detail": "Apps dispatch secrets:write:set, secrets:write:delete and the list query through the exported constants like ConfigHandlers, instead of string literals."
+  },
+  {
+    "version": "0.369.0",
+    "type": "fix",
+    "title": "secrets:write:set and secrets:write:delete join the request transaction",
+    "detail": "Both handlers ran on the boot database connection, so in an /api/batch a later failing command rolled back the config writes but kept the stored secret. They now run on the request transaction (escape hatch unsafeRaw, reason documented on the handler), so a batch of config and secret writes is stored as a whole or not at all."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/secrets/constants.ts

@@ -19,4 +19,13 @@ export const SECRETS_ERROR_KEYS = {
   invalidValue: "secrets.errors.invalidValue",
 } as const;
 
+export const SecretsHandlers = {
+  set: "secrets:write:set",
+  delete: "secrets:write:delete",
+} as const;
+
+export const SecretsQueries = {
+  list: "secrets:query:list",
+} as const;
+
 export const INVALID_SECRET_VALUE_CODE = "invalid_secret_value" as const;

package/packages/bundled-features/src/secrets/db/queries/read.ts

@@ -1,7 +1,7 @@
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import type { StoredEnvelope } from "../../table.js";
+import type { StoredEnvelope } from "../../table.ts";
 
 export async function selectTenantSecretEnvelope(
   db: DbRunner,

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

@@ -3,19 +3,21 @@ import {
   type AccessRule,
   defineFeature,
   type FeatureDefinition,
+  SYSTEM_ROLE,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { type FeatureWithEnvSchema, featureWithEnvSchema } from "@cosmicdrift/kumiko-framework/env";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { SETTINGS_HUB_I18N } from "@cosmicdrift/kumiko-framework/i18n";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import * as z from "zod";
-import { DEFAULT_SECRETS_ACCESS } from "./constants.js";
-import { createDeleteHandler } from "./handlers/delete.write.js";
-import { createListHandler } from "./handlers/list.query.js";
-import { rotateJob } from "./handlers/rotate.job.js";
-import { createSetHandler } from "./handlers/set.write.js";
-import { SECRETS_I18N } from "./i18n.js";
-import { secretReadSchema } from "./secrets-context.js";
-import { tenantSecretEntity, tenantSecretsTable } from "./table.js";
+import { DEFAULT_SECRETS_ACCESS } from "./constants.ts";
+import { createDeleteHandler } from "./handlers/delete.write.ts";
+import { createListHandler } from "./handlers/list.query.ts";
+import { rotateJob } from "./handlers/rotate.job.ts";
+import { createSetHandler } from "./handlers/set.write.ts";
+import { SECRETS_I18N } from "./i18n.ts";
+import { secretReadSchema } from "./secrets-context.ts";
+import { tenantSecretEntity, tenantSecretsTable } from "./table.ts";
 
 const ROTATE_ESCAPE_HATCH_REASON = "re-encrypts every tenant's secrets with the new master key";
 
@@ -60,8 +62,13 @@ export {
   type SecretsContext,
   type SecretsContextOptions,
   TENANT_SECRET_READ_EVENT,
-} from "./secrets-context.js";
-export { type StoredEnvelope, type StoredMetadata, tenantSecretsTable } from "./table.js";
+} from "./secrets-context.ts";
+export { type StoredEnvelope, type StoredMetadata, tenantSecretsTable } from "./table.ts";
+
+// The settings form saves config values and secrets in one /api/batch; the secret
+// write has to join that transaction so a rejected command rolls it back too.
+export const JOIN_REQUEST_TRANSACTION_REASON =
+  "the secret write runs on the request transaction so a failing batch rolls it back together with the config writes";
 
 // AppContext carries ctx.secrets via extraContext. requireSecretsContext
 // wraps that raw context so every `.get(...)` call auto-includes the
@@ -133,11 +140,22 @@ function resolveSecretsAccess(opts: SecretsFeatureOptions): AccessRule {
   return DEFAULT_SECRETS_ACCESS;
 }
 
-export function createSecretsFeature(opts: SecretsFeatureOptions = {}): FeatureDefinition {
+// Server-side system writes (dispatchSystemWrite, e.g. a wire hook migrating credentials) take the
+// same declared-key gate, value check and cache-sync announce as an admin instead of bypassing them
+// via SecretsContext.set. The system role is in-process only and never minted into a session.
+function withSystemWriter(rule: AccessRule): AccessRule {
+  if (!("roles" in rule) || rule.roles.includes(SYSTEM_ROLE)) return rule;
+  return { ...rule, roles: [SYSTEM_ROLE, ...rule.roles] };
+}
+
+export function createSecretsFeature(
+  opts: SecretsFeatureOptions = {},
+): FeatureWithEnvSchema<FeatureDefinition, typeof secretsEnvSchema.shape> {
   const access = resolveSecretsAccess(opts);
-  return defineFeature(SECRETS_FEATURE_NAME, (r) => {
+  const writeAccess = withSystemWriter(access);
+  const feature: FeatureDefinition = 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. 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: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins).',
+      '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: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins). Server-side code writes a tenant secret with `dispatchSystemWrite({ handlerQn: SecretsHandlers.set, payload, tenantId })`: set and delete also admit the in-process system identity, so such writes pass the same declared-key and value checks.',
     );
     r.uiHints({
       displayLabel: "Tenant Secrets",
@@ -177,8 +195,8 @@ export function createSecretsFeature(opts: SecretsFeatureOptions = {}): FeatureD
     // The rotation job deliberately reaches for ctx.db.unsafeRaw() (raw,
     // cross-tenant) because rotation is a deployment-wide operation — no
     // feature-wide r.systemScope() needed.
-    r.writeHandler(createSetHandler(access));
-    r.writeHandler(createDeleteHandler(access));
+    r.writeHandler(createSetHandler(writeAccess));
+    r.writeHandler(createDeleteHandler(writeAccess));
     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
@@ -204,4 +222,5 @@ export function createSecretsFeature(opts: SecretsFeatureOptions = {}): FeatureD
     // ops-tool (see docs/plans/architecture/event-dispatcher.md §retention).
     // No per-feature retention-job anymore.
   });
+  return featureWithEnvSchema(feature, secretsEnvSchema);
 }

package/packages/bundled-features/src/secrets/handlers/delete.write.ts

@@ -1,10 +1,10 @@
 import { type AccessRule, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { announceSecretChange } from "../announce-secret-change.js";
-import { DEFAULT_SECRETS_ACCESS } from "../constants.js";
-import { requireSecretsContext } from "../feature.js";
-import { checkSecretKeyWrite } from "../write-gate.js";
+import { announceSecretChange } from "../announce-secret-change.ts";
+import { DEFAULT_SECRETS_ACCESS, SecretsHandlers } from "../constants.ts";
+import { JOIN_REQUEST_TRANSACTION_REASON, requireSecretsContext } from "../feature.ts";
+import { checkSecretKeyWrite } from "../write-gate.ts";
 
 export function createDeleteHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
   return defineWriteHandler({
@@ -16,8 +16,11 @@ export function createDeleteHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS)
       key: z.string().min(1).max(100),
     }),
     access,
+    escapeHatch: { grants: ["unsafeRaw"], reason: JOIN_REQUEST_TRANSACTION_REASON },
     handler: async (event, ctx) => {
-      const secrets = requireSecretsContext(ctx, "secrets:write:delete");
+      const secrets = requireSecretsContext(ctx, SecretsHandlers.delete).withRunner(
+        ctx.db.unsafeRaw(),
+      );
       const gate = checkSecretKeyWrite(ctx.registry, event.user.roles, event.payload.key, {
         allowUndeclared: true,
       });

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

@@ -1,7 +1,7 @@
 import { type AccessRule, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { DEFAULT_SECRETS_ACCESS } from "../constants.js";
-import { tenantSecretsTable } from "../table.js";
+import { DEFAULT_SECRETS_ACCESS } from "../constants.ts";
+import { tenantSecretsTable } from "../table.ts";
 
 // Lists all secrets for the current tenant. Returns redactedPreview, never
 // the plaintext. Decryption would be pointless here anyway — this is the

package/packages/bundled-features/src/secrets/handlers/rotate.job.ts

@@ -31,8 +31,8 @@ import {
   encodeStoredEnvelope,
   rewrapDek,
 } from "@cosmicdrift/kumiko-framework/secrets";
-import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared/index.js";
-import { type StoredEnvelope, tenantSecretEntity, tenantSecretsTable } from "../table.js";
+import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared/index.ts";
+import { type StoredEnvelope, tenantSecretEntity, tenantSecretsTable } from "../table.ts";
 
 const DEFAULT_BATCH_SIZE = 100;
 const DEFAULT_MAX_FAILURES = 10;

package/packages/bundled-features/src/secrets/handlers/set.write.ts

@@ -1,9 +1,9 @@
 import { type AccessRule, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { announceSecretChange } from "../announce-secret-change.js";
-import { DEFAULT_SECRETS_ACCESS } from "../constants.js";
-import { requireSecretsContext } from "../feature.js";
-import { checkSecretKeyWrite, checkSecretValue } from "../write-gate.js";
+import { announceSecretChange } from "../announce-secret-change.ts";
+import { DEFAULT_SECRETS_ACCESS, SecretsHandlers } from "../constants.ts";
+import { JOIN_REQUEST_TRANSACTION_REASON, requireSecretsContext } from "../feature.ts";
+import { checkSecretKeyWrite, checkSecretValue } from "../write-gate.ts";
 
 export function createSetHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
   return defineWriteHandler({
@@ -23,8 +23,11 @@ export function createSetHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
       hint: z.string().max(200).optional(),
     }),
     access,
+    escapeHatch: { grants: ["unsafeRaw"], reason: JOIN_REQUEST_TRANSACTION_REASON },
     handler: async (event, ctx) => {
-      const secrets = requireSecretsContext(ctx, "secrets:write:set");
+      const secrets = requireSecretsContext(ctx, SecretsHandlers.set).withRunner(
+        ctx.db.unsafeRaw(),
+      );
       const { key, value, redactedPreview, hint } = event.payload;
 
       // Preview-priority: explicit payload param > feature-declared redact

package/packages/bundled-features/src/secrets/i18n.ts

@@ -1,4 +1,4 @@
-import { SECRETS_ERROR_KEYS } from "./constants.js";
+import { SECRETS_ERROR_KEYS } from "./constants.ts";
 
 export const SECRETS_I18N = {
   [SECRETS_ERROR_KEYS.unknownKey]: {