@cosmicdrift/kumiko-bundled-features 0.345.0 → 0.346.0

package/dist/audit/constants.d.ts

@@ -9,6 +9,13 @@ export declare const AuditQueries: {
     readonly list: "audit:query:list";
     readonly details: "audit:query:details";
 };
+/** Read scope of the audit queries: the caller's own tenant (default) or the system tenant (SystemAdmin only). */
+export declare const AuditScopes: {
+    readonly tenant: "tenant";
+    readonly system: "system";
+};
+export type AuditScope = (typeof AuditScopes)[keyof typeof AuditScopes];
+export declare const AUDIT_SCOPE_VALUES: readonly ["tenant", "system"];
 /** Tenant-admin audit log screen. Nav: `audit:screen:audit-log`. */
 export declare const AUDIT_LOG_SCREEN_ID: "audit-log";
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */

package/dist/audit/constants.js

@@ -14,6 +14,9 @@ export const AuditQueries = {
     list: "audit:query:list",
     details: "audit:query:details",
 };
+/** Read scope of the audit queries: the caller's own tenant (default) or the system tenant (SystemAdmin only). */
+export const AuditScopes = { tenant: "tenant", system: "system" };
+export const AUDIT_SCOPE_VALUES = [AuditScopes.tenant, AuditScopes.system];
 /** Tenant-admin audit log screen. Nav: `audit:screen:audit-log`. */
 export const AUDIT_LOG_SCREEN_ID = "audit-log";
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */

package/dist/audit/feature.js

@@ -20,7 +20,7 @@ import { runEscapeHatchRetention } from "./run-escape-hatch-retention.js";
 // framework).
 export function createAuditFeature() {
     return defineFeature("audit", (r) => {
-        r.describe("Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).");
+        r.describe("Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).");
         r.uiHints({
             displayLabel: "Audit Log",
             category: "compliance",

package/dist/audit/handlers/details.query.d.ts

@@ -1,6 +1,10 @@
 import * as z from "zod";
 export declare const detailsQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"details", z.ZodObject<{
     id: z.ZodString;
+    scope: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        tenant: "tenant";
+    }>>;
 }, z.core.$strip>, {
     id: string;
     aggregateId: string;

package/dist/audit/handlers/details.query.js

@@ -1,19 +1,30 @@
 // Single audit event by its event-store id — backs the audit-log-detail
 // screen. Tenant-isolated at the WHERE level like list.query, so a caller
-// can only read events in their own tenant.
+// can only read events in their own tenant; a SystemAdmin can pass scope
+// "system" to read app-instance system events (e.g. app.started).
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import * as z from "zod";
+import { AUDIT_SCOPE_VALUES } from "../constants.js";
+import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 export const detailsQuery = defineQueryHandler({
     name: "details",
-    description: "Returns one audit-trail event of the caller's tenant by its event-store id, with full payload and metadata; use it to inspect the exact change behind a row of the audit log list.",
+    description: 'Returns one audit-trail event of the caller\'s tenant by its event-store id, with full payload and metadata; use it to inspect the exact change behind a row of the audit log list. A SystemAdmin can set scope "system" to read an app-instance system event (e.g. app.started).',
     schema: z.object({
         id: z.string().regex(/^[1-9]\d*$/, "id must be a positive integer"),
+        scope: z.enum(AUDIT_SCOPE_VALUES).optional(),
     }),
     access: { roles: access.admin },
     handler: async (query, ctx) => {
-        const rows = await selectMany(ctx.db, eventsTable, { tenantId: query.user.tenantId, id: BigInt(query.payload.id) }, { limit: 1 });
+        const scopeFilter = resolveAuditScopeFilter(query.user, query.payload.scope);
+        const rows = await selectMany(ctx.db, eventsTable, {
+            tenantId: scopeFilter.tenantId,
+            ...(scopeFilter.aggregateType !== undefined && {
+                aggregateType: scopeFilter.aggregateType,
+            }),
+            id: BigInt(query.payload.id),
+        }, { limit: 1 });
         const row = rows[0];
         if (row === undefined)
             return null;

package/dist/audit/handlers/list.query.d.ts

@@ -18,6 +18,10 @@ export declare const listQuery: import("@cosmicdrift/kumiko-types/define-handler
     }>>;
     from: z.ZodOptional<z.ZodISODateTime>;
     to: z.ZodOptional<z.ZodISODateTime>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        tenant: "tenant";
+    }>>;
 }, z.core.$strip>, {
     rows: {
         id: string;

package/dist/audit/handlers/list.query.js

@@ -6,6 +6,8 @@
 // No projection, no separate audit table. Queryable with the same filter
 // surface any audit UI needs; tenant-isolated at the WHERE level so cross-
 // tenant peeking is structurally impossible for non-SystemAdmin callers.
+// A SystemAdmin can pass scope "system" to read the app-instance system events
+// (e.g. app.started); no other cross-tenant read exists.
 //
 // Sensitive field-values are ciphertext inside the event payload (the log
 // carries them encrypted); stripSensitive only strips the event echo. This
@@ -16,6 +18,8 @@ import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "temporal-polyfill";
 import * as z from "zod";
+import { AUDIT_SCOPE_VALUES } from "../constants.js";
+import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 const MAX_LIMIT = 100;
 function buildDateRange(from, to) {
     if (!from && !to)
@@ -52,7 +56,7 @@ function buildAuditWhere(tenantId, p) {
 }
 export const listQuery = defineQueryHandler({
     name: "list",
-    description: "Lists the tenant's audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when.",
+    description: 'Lists the tenant\'s audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when. A SystemAdmin can set scope "system" to read the app-instance system events (e.g. app.started) instead of the own tenant.',
     schema: z
         .object({
         cursor: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
@@ -67,6 +71,7 @@ export const listQuery = defineQueryHandler({
         sortDirection: z.enum(["asc", "desc"]).optional(),
         from: z.iso.datetime().optional(),
         to: z.iso.datetime().optional(),
+        scope: z.enum(AUDIT_SCOPE_VALUES).optional(),
     })
         .refine((v) => !v.from || !v.to || v.from <= v.to, {
         message: "`from` must be less than or equal to `to`",
@@ -75,7 +80,11 @@ export const listQuery = defineQueryHandler({
     access: { roles: access.admin },
     handler: async (query, ctx) => {
         const p = query.payload;
-        const where = buildAuditWhere(query.user.tenantId, p);
+        const scopeFilter = resolveAuditScopeFilter(query.user, p.scope);
+        const where = buildAuditWhere(scopeFilter.tenantId, {
+            ...p,
+            aggregateType: scopeFilter.aggregateType ?? p.aggregateType,
+        });
         const rows = await selectMany(ctx.db, eventsTable, where, {
             orderBy: {
                 col: query.payload.sort === "type" ? "type" : "createdAt",

package/dist/audit/handlers/resolve-audit-tenant.d.ts

@@ -0,0 +1,7 @@
+import { type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { type AuditScope } from "../constants.js";
+export type AuditScopeFilter = {
+    readonly tenantId: string;
+    readonly aggregateType?: string;
+};
+export declare function resolveAuditScopeFilter(user: SessionUser, scope: AuditScope | undefined): AuditScopeFilter;

package/dist/audit/handlers/resolve-audit-tenant.js

@@ -0,0 +1,14 @@
+import { crossTenantOverrideDenied } from "@cosmicdrift/kumiko-framework/engine";
+import { APP_INSTANCE_STREAM_TYPE } from "@cosmicdrift/kumiko-framework/event-store";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import { AuditScopes } from "../constants.js";
+// The system tenant also holds personal streams of other features (session
+// revocations, exports, ...); only app-instance streams are released.
+export function resolveAuditScopeFilter(user, scope) {
+    if (scope !== AuditScopes.system)
+        return { tenantId: user.tenantId };
+    const denied = crossTenantOverrideDenied(user, SYSTEM_TENANT_ID, "audit.errors.systemScopeRequiresSystemAdmin");
+    if (denied)
+        throw denied;
+    return { tenantId: SYSTEM_TENANT_ID, aggregateType: APP_INSTANCE_STREAM_TYPE };
+}

package/dist/audit/i18n.js

@@ -6,6 +6,9 @@ export const AUDIT_I18N = {
     "audit.log.detail.subtitle": {
         en: "Read-only detail view of one audit event showing actor, timestamp, aggregate and the raw event payload and metadata; reached from a row of the audit log.",
     },
+    "audit.errors.systemScopeRequiresSystemAdmin": {
+        en: "Only SystemAdmin may read system events.",
+    },
     "audit:nav.auditLog": { en: "Audit" },
     "audit.log.col.when": { en: "When" },
     "audit.log.col.type": { en: "Event" },

package/dist/billing-foundation/subscription-tier-sync.js

@@ -2,7 +2,7 @@
 // near-identical webhook-route.ts app copies in show-pony and publicstatus
 // (infra#446) — the only per-app variables were the TierName union/default,
 // so it is now a factory parameter.
-import { TierEngineHandlers, TierEngineQueries, tierAssignmentAggregateId, } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
+import { TierAssignmentSources, TierEngineHandlers, TierEngineQueries, tierAssignmentAggregateId, } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
 import { subscriptionAggregateId } from "./aggregate-id.js";
 import { SubscriptionFoundationQueries, SubscriptionStatuses } from "./constants.js";
 import { createSubscriptionWebhookRoute } from "./webhook-handler.js";
@@ -25,6 +25,13 @@ function asRows(result) {
     }
     throw new Error("expected a { rows: [...] } list-query result");
 }
+function findTierAssignment(rows, tenantId) {
+    const row = rows.find((candidate) => candidate["tenantId"] === tenantId);
+    if (!row || typeof row["id"] !== "string" || typeof row["version"] !== "number") {
+        return undefined;
+    }
+    return { id: row["id"], version: row["version"], tier: row["tier"], source: row["source"] };
+}
 export function createSubscriptionTierSync(deps) {
     async function syncTierFromSubscription(tenantId, routeDeps) {
         try {
@@ -43,13 +50,15 @@ export function createSubscriptionTierSync(deps) {
                 payload: {},
                 tenantId,
             }));
-            const assignment = tierAssignmentRows.find((row) => row["tenantId"] === tenantId);
-            if (!assignment ||
-                typeof assignment["id"] !== "string" ||
-                typeof assignment["version"] !== "number") {
+            const assignment = findTierAssignment(tierAssignmentRows, tenantId);
+            if (!assignment) {
                 const created = await routeDeps.dispatchSystemWrite({
                     handlerQn: TierEngineHandlers.create,
-                    payload: { id: tierAssignmentAggregateId(tenantId), tier: effective },
+                    payload: {
+                        id: tierAssignmentAggregateId(tenantId),
+                        tier: effective,
+                        source: TierAssignmentSources.billing,
+                    },
                     tenantId,
                 });
                 if (!created.isSuccess) {
@@ -60,14 +69,16 @@ export function createSubscriptionTierSync(deps) {
                 }
                 return null;
             }
-            if (assignment["tier"] === effective)
+            if (assignment.source === TierAssignmentSources.manual)
+                return null;
+            if (assignment.tier === effective)
                 return null;
             const result = await routeDeps.dispatchSystemWrite({
                 handlerQn: TierEngineHandlers.update,
                 payload: {
-                    id: assignment["id"],
-                    version: assignment["version"],
-                    changes: { tier: effective },
+                    id: assignment.id,
+                    version: assignment.version,
+                    changes: { tier: effective, source: TierAssignmentSources.billing },
                 },
                 tenantId,
             });

package/dist/step-dispatcher/dispatch-payload.d.ts

@@ -0,0 +1,49 @@
+import * as z from "zod";
+import { type MailSpec } from "./mail-runner.js";
+import { type WebhookSpec } from "./webhook-runner.js";
+export declare const dispatchRequestedPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    stepKind: z.ZodLiteral<"webhook.send">;
+    url: z.ZodString;
+    method: z.ZodEnum<{
+        PATCH: "PATCH";
+        POST: "POST";
+        PUT: "PUT";
+    }>;
+    headersJson: z.ZodString;
+    bodyJson: z.ZodOptional<z.ZodString>;
+    auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"bearer">;
+        secret: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"header">;
+        name: z.ZodString;
+        secret: z.ZodString;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>, z.ZodObject<{
+    stepKind: z.ZodLiteral<"mail.send">;
+    to: z.ZodString;
+    subject: z.ZodString;
+    body: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "stepKind">;
+type DispatchRequestedPayload = z.infer<typeof dispatchRequestedPayloadSchema>;
+export declare function rawStepKindOf(payload: unknown): string;
+type PayloadFieldName = "to" | "subject" | "body" | "from" | "url" | "headersJson" | "bodyJson";
+type ReadPayloadResult = {
+    readonly kind: "ready";
+    readonly fields: Readonly<Partial<Record<PayloadFieldName, string>>>;
+} | {
+    readonly kind: "erased";
+} | {
+    readonly kind: "unreadable";
+};
+export declare function readPayloadFields(payload: DispatchRequestedPayload): Promise<ReadPayloadResult>;
+type DispatchSpec = {
+    readonly stepKind: "mail.send";
+    readonly spec: MailSpec;
+} | {
+    readonly stepKind: "webhook.send";
+    readonly spec: WebhookSpec;
+};
+export declare function buildDispatchSpec(payload: DispatchRequestedPayload, fields: Readonly<Partial<Record<PayloadFieldName, string>>>): DispatchSpec | null;
+export {};

package/dist/step-dispatcher/dispatch-payload.js

@@ -0,0 +1,115 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import { configuredPiiSubjectKms, decryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, } from "@cosmicdrift/kumiko-framework/crypto";
+import * as z from "zod";
+import { mailSpecSchema } from "./mail-runner.js";
+import { webhookSpecSchema } from "./webhook-runner.js";
+// PII fields of the flat payload are ciphertext under the per-dispatch
+// record key (system-event-pii.ts). `to`/`headersJson`/`bodyJson` are JSON
+// strings because event PII encryption only handles top-level strings.
+// Runtime-validated instead of cast — `event.payload` is `unknown` at the
+// MSP-apply boundary, so a payload in another shape must end as
+// dispatch-failed, never reach the runners.
+export const dispatchRequestedPayloadSchema = z.discriminatedUnion("stepKind", [
+    z.object({
+        stepKind: z.literal("webhook.send"),
+        url: z.string(),
+        method: webhookSpecSchema.shape.method,
+        headersJson: z.string(),
+        bodyJson: z.string().optional(),
+        auth: webhookSpecSchema.shape.auth,
+    }),
+    z.object({
+        stepKind: z.literal("mail.send"),
+        to: z.string(),
+        subject: z.string(),
+        body: z.string(),
+        from: z.string().optional(),
+    }),
+]);
+const rawStepKindSchema = z.object({ stepKind: z.string() });
+export function rawStepKindOf(payload) {
+    const parsed = rawStepKindSchema.safeParse(payload);
+    return parsed.success ? parsed.data.stepKind : "unknown";
+}
+const jsonStringSchema = z.string().transform((raw, refinementCtx) => {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        refinementCtx.addIssue({ code: "custom", message: "invalid json" });
+        return z.NEVER;
+    }
+});
+const headersJsonSchema = jsonStringSchema.pipe(z.record(z.string(), z.string()));
+const mailToJsonSchema = jsonStringSchema.pipe(mailSpecSchema.shape.to);
+function piiFieldsOf(payload) {
+    return payload.stepKind === "mail.send"
+        ? ["to", "subject", "body", "from"]
+        : ["url", "headersJson", "bodyJson"];
+}
+function payloadFieldValue(payload, field) {
+    const values = payload.stepKind === "mail.send"
+        ? { to: payload.to, subject: payload.subject, body: payload.body, from: payload.from }
+        : { url: payload.url, headersJson: payload.headersJson, bodyJson: payload.bodyJson };
+    return values[field];
+}
+export async function readPayloadFields(payload) {
+    const kms = configuredPiiSubjectKms();
+    const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
+    const fields = {};
+    for (const field of piiFieldsOf(payload)) {
+        const value = payloadFieldValue(payload, field);
+        if (value === undefined)
+            continue;
+        if (!isPiiCiphertext(value)) {
+            fields[field] = value;
+            continue;
+        }
+        if (!kms)
+            return { kind: "unreadable" };
+        const plain = await decryptPiiValueForSubject(kms, value, { requestId }, field);
+        if (plain === PII_ERASED_SENTINEL)
+            return { kind: "erased" };
+        fields[field] = plain;
+    }
+    return { kind: "ready", fields };
+}
+// Parse failures return null — the caller records a generic error, never the
+// (decrypted) values.
+export function buildDispatchSpec(payload, fields) {
+    if (payload.stepKind === "mail.send") {
+        const to = mailToJsonSchema.safeParse(fields.to);
+        if (!to.success || fields.subject === undefined || fields.body === undefined)
+            return null;
+        return {
+            stepKind: "mail.send",
+            spec: {
+                to: to.data,
+                subject: fields.subject,
+                body: fields.body,
+                ...(fields.from !== undefined && { from: fields.from }),
+            },
+        };
+    }
+    const headers = headersJsonSchema.safeParse(fields.headersJson);
+    if (!headers.success || fields.url === undefined)
+        return null;
+    let body;
+    if (fields.bodyJson !== undefined) {
+        const parsedBody = jsonStringSchema.safeParse(fields.bodyJson);
+        if (!parsedBody.success)
+            return null;
+        body = parsedBody.data;
+    }
+    return {
+        stepKind: "webhook.send",
+        spec: {
+            url: fields.url,
+            method: payload.method,
+            headers: headers.data,
+            ...(body !== undefined && { body }),
+            ...(payload.auth && { auth: payload.auth }),
+        },
+    };
+}

package/dist/step-dispatcher/feature.js

@@ -7,14 +7,15 @@
 // or `kumiko:system:step.dispatch-failed` back onto the same stream so
 // the audit trail lives in the event log only — no separate status table.
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
-import { configuredPiiSubjectKms, decryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, } from "@cosmicdrift/kumiko-framework/crypto";
+import { configuredPiiSubjectKms } from "@cosmicdrift/kumiko-framework/crypto";
 import { defineFeature, STEP_DISPATCH_AGGREGATE_TYPE, STEP_DISPATCH_FAILED_TYPE, STEP_DISPATCH_REQUESTED_TYPE, STEP_DISPATCHED_TYPE, } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
 import * as z from "zod";
 import { redactEmailAddresses } from "../shared/index.js";
-import { mailSpecSchema, performMailDispatch } from "./mail-runner.js";
-import { performWebhookDispatch, WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR, WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS, webhookSpecSchema, } from "./webhook-runner.js";
+import { buildDispatchSpec, dispatchRequestedPayloadSchema, rawStepKindOf, readPayloadFields, } from "./dispatch-payload.js";
+import { performMailDispatch } from "./mail-runner.js";
+import { performWebhookDispatch, WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR, WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS, } from "./webhook-runner.js";
 const log = createFallbackLogger("step-dispatcher");
 export const stepDispatcherEnvSchema = z.object({
     [WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
@@ -23,30 +24,6 @@ export const stepDispatcherEnvSchema = z.object({
         .describe("Comma-separated operator allowlist of private/internal hosts (e.g. a local webhook-receiver for dev/test) that bypass the public-address check for webhook.send targets. Never a tenant-config value."),
 });
 export { STEP_DISPATCH_AGGREGATE_TYPE };
-// PII fields of the flat payload are ciphertext under the per-dispatch
-// record key (system-event-pii.ts). `to`/`headersJson`/`bodyJson` are JSON
-// strings because event PII encryption only handles top-level strings.
-// Runtime-validated instead of cast — `event.payload` is `unknown` at the
-// MSP-apply boundary, so a payload in another shape must end as
-// dispatch-failed, never reach the runners.
-const dispatchRequestedPayloadSchema = z.discriminatedUnion("stepKind", [
-    z.object({
-        stepKind: z.literal("webhook.send"),
-        url: z.string(),
-        method: webhookSpecSchema.shape.method,
-        headersJson: z.string(),
-        bodyJson: z.string().optional(),
-        auth: webhookSpecSchema.shape.auth,
-        retry: z.object({ times: z.number(), backoff: z.enum(["exponential", "linear"]) }).optional(),
-    }),
-    z.object({
-        stepKind: z.literal("mail.send"),
-        to: z.string(),
-        subject: z.string(),
-        body: z.string(),
-        from: z.string().optional(),
-    }),
-]);
 // zod issue messages can echo the invalid value (e.g. a rejected url) back
 // into the tenant-visible dispatch-failed event — keep this generic.
 const INVALID_DISPATCH_PAYLOAD_ERROR = "invalid dispatch payload";
@@ -55,92 +32,8 @@ const PAYLOAD_UNREADABLE_ERROR = "dispatch payload is not readable";
 // dispatch-failed text outlives the payload erase, so only this is persisted.
 const MAIL_DELIVERY_FAILED_ERROR = "mail delivery failed";
 const PAYLOAD_ERASED_ERROR = "dispatch payload erased before an outcome was recorded";
-const rawStepKindSchema = z.object({ stepKind: z.string() });
-function rawStepKindOf(payload) {
-    const parsed = rawStepKindSchema.safeParse(payload);
-    return parsed.success ? parsed.data.stepKind : "unknown";
-}
-const jsonStringSchema = z.string().transform((raw, refinementCtx) => {
-    try {
-        const parsed = JSON.parse(raw);
-        return parsed;
-    }
-    catch {
-        refinementCtx.addIssue({ code: "custom", message: "invalid json" });
-        return z.NEVER;
-    }
-});
-const headersJsonSchema = jsonStringSchema.pipe(z.record(z.string(), z.string()));
-const mailToJsonSchema = jsonStringSchema.pipe(mailSpecSchema.shape.to);
-function piiFieldsOf(payload) {
-    return payload.stepKind === "mail.send"
-        ? ["to", "subject", "body", "from"]
-        : ["url", "headersJson", "bodyJson"];
-}
-function payloadFieldValue(payload, field) {
-    const values = payload.stepKind === "mail.send"
-        ? { to: payload.to, subject: payload.subject, body: payload.body, from: payload.from }
-        : { url: payload.url, headersJson: payload.headersJson, bodyJson: payload.bodyJson };
-    return values[field];
-}
-async function readPayloadFields(payload) {
-    const kms = configuredPiiSubjectKms();
-    const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
-    const fields = {};
-    for (const field of piiFieldsOf(payload)) {
-        const value = payloadFieldValue(payload, field);
-        if (value === undefined)
-            continue;
-        if (!isPiiCiphertext(value)) {
-            fields[field] = value;
-            continue;
-        }
-        if (!kms)
-            return { kind: "unreadable" };
-        const plain = await decryptPiiValueForSubject(kms, value, { requestId }, field);
-        if (plain === PII_ERASED_SENTINEL)
-            return { kind: "erased" };
-        fields[field] = plain;
-    }
-    return { kind: "ready", fields };
-}
-// Parse failures return null — the caller records a generic error, never the
-// (decrypted) values.
-function buildDispatchSpec(payload, fields) {
-    if (payload.stepKind === "mail.send") {
-        const to = mailToJsonSchema.safeParse(fields.to);
-        if (!to.success || fields.subject === undefined || fields.body === undefined)
-            return null;
-        return {
-            stepKind: "mail.send",
-            spec: {
-                to: to.data,
-                subject: fields.subject,
-                body: fields.body,
-                ...(fields.from !== undefined && { from: fields.from }),
-            },
-        };
-    }
-    const headers = headersJsonSchema.safeParse(fields.headersJson);
-    if (!headers.success || fields.url === undefined)
-        return null;
-    let body;
-    if (fields.bodyJson !== undefined) {
-        const parsedBody = jsonStringSchema.safeParse(fields.bodyJson);
-        if (!parsedBody.success)
-            return null;
-        body = parsedBody.data;
-    }
-    return {
-        stepKind: "webhook.send",
-        spec: {
-            url: fields.url,
-            method: payload.method,
-            headers: headers.data,
-            ...(body !== undefined && { body }),
-            ...(payload.auth && { auth: payload.auth }),
-        },
-    };
+function isDispatchOutcome(e) {
+    return e.type === STEP_DISPATCHED_TYPE || e.type === STEP_DISPATCH_FAILED_TYPE;
 }
 export function createStepDispatcherFeature() {
     return defineFeature("step-dispatcher", (r) => {
@@ -159,9 +52,16 @@ export function createStepDispatcherFeature() {
                 [STEP_DISPATCH_REQUESTED_TYPE]: async (event, _tx, ctx) => {
                     const kms = configuredPiiSubjectKms();
                     const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
+                    const eraseDispatchKey = async () => {
+                        await kms?.eraseKey({ kind: "record", entity: STEP_DISPATCH_AGGREGATE_TYPE, id: event.aggregateId }, { requestId, eraseReason: "step-dispatch-outcome-recorded" });
+                    };
                     // Outcome events are plaintext and generic; the request payload's
                     // per-dispatch key is erased right after, so the PII dies with the
-                    // dispatch instead of living in the event log.
+                    // dispatch instead of living in the event log. The outcome is
+                    // appended before the erase on purpose: if the erase throws, the
+                    // outcome survives and a redelivery only repeats the erase. A crash
+                    // between the send and the outcome append still re-sends under the
+                    // same Idempotency-Key — the one remaining double-send case.
                     const recordOutcome = async (type, payload) => {
                         await ctx.unsafeAppendEvent({
                             aggregateId: event.aggregateId,
@@ -169,9 +69,15 @@ export function createStepDispatcherFeature() {
                             type,
                             payload,
                         });
-                        await kms?.eraseKey({ kind: "record", entity: STEP_DISPATCH_AGGREGATE_TYPE, id: event.aggregateId }, { requestId, eraseReason: "step-dispatch-outcome-recorded" });
+                        await eraseDispatchKey();
                     };
                     const recordFailure = (stepKind, error) => recordOutcome(STEP_DISPATCH_FAILED_TYPE, { stepKind, error, attempt: 1 });
+                    const stream = await ctx.loadAggregate(event.aggregateId);
+                    if (stream.some(isDispatchOutcome)) {
+                        await eraseDispatchKey();
+                        // skip: redelivery after an outcome was recorded — only the erase is repeated
+                        return;
+                    }
                     const parsed = dispatchRequestedPayloadSchema.safeParse(event.payload);
                     if (!parsed.success) {
                         await recordFailure(rawStepKindOf(event.payload), INVALID_DISPATCH_PAYLOAD_ERROR);
@@ -186,11 +92,6 @@ export function createStepDispatcherFeature() {
                         return;
                     }
                     if (read.kind === "erased") {
-                        const stream = await ctx.loadAggregate(event.aggregateId);
-                        const hasOutcome = stream.some((e) => e.type === STEP_DISPATCHED_TYPE || e.type === STEP_DISPATCH_FAILED_TYPE);
-                        // skip: redelivery after the key was erased — the outcome is already recorded
-                        if (hasOutcome)
-                            return;
                         await recordFailure(payload.stepKind, PAYLOAD_ERASED_ERROR);
                         // skip: erased payload recorded via step.dispatch-failed above
                         return;

package/dist/step-dispatcher/webhook-runner.d.ts

@@ -46,6 +46,8 @@ export type WebhookDispatchDeps = {
     readonly userId: string;
     readonly secrets: SecretsContext | undefined;
     readonly idempotencyKey: string;
+    readonly requestTimeoutMs?: number;
 };
+export declare const WEBHOOK_REQUEST_TIMEOUT_MS = 10000;
 export declare const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
 export declare function performWebhookDispatch(spec: WebhookSpec, deps: WebhookDispatchDeps): Promise<WebhookDispatchResult>;

package/dist/step-dispatcher/webhook-runner.js

@@ -79,17 +79,32 @@ let fetchImpl = globalThis.fetch.bind(globalThis);
 export function setWebhookFetch(fn) {
     fetchImpl = fn;
 }
+// One hanging tenant-controlled receiver must not stall the shared
+// step-dispatcher consumer for every tenant.
+export const WEBHOOK_REQUEST_TIMEOUT_MS = 10_000;
 // Never includes the secret name or value — spec.auth.secret is a
 // tenant-chosen name, but the error still reaches the tenant via the
 // dispatch-failed event, so it stays generic.
 const WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR = "webhook auth secret is not available";
 export const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
-function hasIdempotencyKeyHeader(headers) {
-    return Object.keys(headers).some((name) => name.toLowerCase() === WEBHOOK_IDEMPOTENCY_KEY_HEADER);
+function hasHeader(headers, lowerCaseName) {
+    return Object.keys(headers).some((name) => name.toLowerCase() === lowerCaseName);
+}
+// Header names are case-insensitive: two keys differing only in case would be
+// comma-joined by `Headers`, so a replacement must drop every spelling first.
+function setHeader(headers, name, value) {
+    const lowerCaseName = name.toLowerCase();
+    for (const existing of Object.keys(headers)) {
+        if (existing.toLowerCase() === lowerCaseName)
+            delete headers[existing];
+    }
+    headers[name] = value;
 }
 async function buildWebhookHeaders(spec, deps) {
-    const headers = { "content-type": "application/json", ...spec.headers };
-    if (!hasIdempotencyKeyHeader(headers)) {
+    const headers = { ...spec.headers };
+    if (!hasHeader(headers, "content-type"))
+        headers["content-type"] = "application/json";
+    if (!hasHeader(headers, WEBHOOK_IDEMPOTENCY_KEY_HEADER)) {
         headers[WEBHOOK_IDEMPOTENCY_KEY_HEADER] = deps.idempotencyKey;
     }
     if (!spec.auth)
@@ -114,10 +129,10 @@ async function buildWebhookHeaders(spec, deps) {
         return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
     }
     if (spec.auth.kind === "bearer") {
-        headers["authorization"] = `Bearer ${secret}`;
+        setHeader(headers, "authorization", `Bearer ${secret}`);
     }
     else {
-        headers[spec.auth.name] = secret;
+        setHeader(headers, spec.auth.name, secret);
     }
     return { ok: true, headers };
 }
@@ -166,6 +181,7 @@ export async function performWebhookDispatch(spec, deps) {
             ...target.requestInit,
             method: spec.method,
             redirect: "manual",
+            signal: AbortSignal.timeout(deps.requestTimeoutMs ?? WEBHOOK_REQUEST_TIMEOUT_MS),
             body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
         });
         if (!res.ok) {

package/dist/tier-engine/constants.d.ts

@@ -4,6 +4,11 @@ export declare const TierEngineHandlers: {
     readonly update: "tier-engine:write:tier-assignment:update";
     readonly setTenantTier: "tier-engine:write:set-tenant-tier";
 };
+export declare const TierAssignmentSources: {
+    readonly manual: "manual";
+    readonly billing: "billing";
+    readonly default: "default";
+};
 export declare const TierEngineQueries: {
     readonly list: "tier-engine:query:tier-assignment:list";
     readonly getActiveTier: "tier-engine:query:get-active-tier";

package/dist/tier-engine/constants.js

@@ -13,6 +13,12 @@ export const TierEngineHandlers = {
     update: "tier-engine:write:tier-assignment:update",
     setTenantTier: "tier-engine:write:set-tenant-tier",
 };
+// Origin of a tier-assignment row; the billing sync must not touch "manual" rows.
+export const TierAssignmentSources = {
+    manual: "manual",
+    billing: "billing",
+    default: "default",
+};
 // Qualified query handler names.
 export const TierEngineQueries = {
     list: "tier-engine:query:tier-assignment:list",

package/dist/tier-engine/entity.js

@@ -31,10 +31,8 @@ export const tierAssignmentEntity = createEntity({
             personal: false,
             reason: "catalog_label",
         }),
-        // Woher das Assignment stammt: "manual" (Admin-Grant via tier-admin-Screen),
-        // "stripe" (future Billing-Sync), "default" (auto-default-on-signup-Hook).
-        // Optional für Back-Compat zu bestehenden Rows ohne source. Schützt manuelle
-        // Grants davor, von einem späteren Stripe→Tier-Sync geplättet zu werden.
+        // Origin of the assignment, see TierAssignmentSources. Optional for back-compat with
+        // rows without source. Protects manual grants from being overwritten by the billing sync.
         source: createTextField({
             required: false,
             maxLength: 20,

package/dist/tier-engine/feature.js

@@ -50,7 +50,7 @@ import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
 import { tenantTable } from "../tenant/index.js";
 import { tierAssignmentAggregateId } from "./aggregate-id.js";
-import { TIER_ADMIN_SCREEN_ID, TIER_ENGINE_FEATURE, TierEngineHandlers } from "./constants.js";
+import { TIER_ADMIN_SCREEN_ID, TIER_ENGINE_FEATURE, TierAssignmentSources, TierEngineHandlers, } from "./constants.js";
 import { tierAssignmentEntity } from "./entity.js";
 import { getActiveTierQuery } from "./handlers/active-tier.query.js";
 import { getTenantTierQuery } from "./handlers/get-tenant-tier.query.js";
@@ -347,7 +347,7 @@ export function createTierEngineFeature(opts = {}) {
                     roles: ["SystemAdmin"],
                 };
                 const tdb = createTenantDb(rawDb, newTenantId, "system");
-                await tierAssignmentExecutor.create({ id: aggregateId, tier: defaultTier, source: "default" }, systemUser, tdb);
+                await tierAssignmentExecutor.create({ id: aggregateId, tier: defaultTier, source: TierAssignmentSources.default }, systemUser, tdb);
             }, { phase: HookPhases.inTransaction, escapeHatch: { reason: autoDefaultTierHookReason } });
         }
         // Extension-point declaration + self-registration. Pattern analog

package/dist/tier-engine/handlers/set-tenant-tier.write.js

@@ -3,6 +3,7 @@ import { buildEntityTable, createEventStoreExecutor, createTenantDb, } from "@co
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { tierAssignmentAggregateId } from "../aggregate-id.js";
+import { TierAssignmentSources } from "../constants.js";
 import { tierAssignmentEntity } from "../entity.js";
 // SystemAdmin setzt das Tier eines BELIEBIGEN Tenants — manueller Grant ohne
 // Billing. Cross-tenant, daher SystemAdmin-only (kein TenantAdmin: sonst
@@ -16,8 +17,8 @@ import { tierAssignmentEntity } from "../entity.js";
 // funktioniert nur für SYSTEM_TENANT_ID (immer im IN-Filter). Dies ist das
 // auto-default-Hook-Muster (feature.ts), generalisiert auf einen Request-Handler.
 //
-// `source: "manual"` markiert den Grant, damit ein späterer Stripe→Tier-Sync ihn
-// nicht plättet. Upsert: ein Aggregat pro Tenant (deterministische aggregate-id).
+// `source: TierAssignmentSources.manual` marks the grant so the billing sync skips it.
+// Upsert: one aggregate per tenant (deterministic aggregate id).
 //
 // Effective-set invalidation: the executor write does not fire the
 // `tier-assignment:postSave` entity hook, and a per-handler postSave would not
@@ -67,14 +68,19 @@ export function createSetTenantTierWrite(opts = {}) {
                 const result = await executor.update({
                     id: existing.id,
                     version: existing.version,
-                    changes: { tier, source: "manual" },
+                    changes: { tier, source: TierAssignmentSources.manual },
                 }, systemUser, tdb);
                 if (!result.isSuccess)
                     return result;
                 afterCommit(tenantId, tier);
                 return { isSuccess: true, data: { tenantId, tier, isNew: false } };
             }
-            const result = await executor.create({ id: tierAssignmentAggregateId(tenantId), tier, source: "manual", tenantId }, systemUser, tdb);
+            const result = await executor.create({
+                id: tierAssignmentAggregateId(tenantId),
+                tier,
+                source: TierAssignmentSources.manual,
+                tenantId,
+            }, systemUser, tdb);
             if (!result.isSuccess)
                 return result;
             afterCommit(tenantId, tier);

package/dist/tier-engine/index.d.ts

@@ -1,6 +1,6 @@
 export { tierAssignmentAggregateId } from "./aggregate-id.js";
 export { type AddOnDefinition, type AddOnMap, type ComposeAppInput, type ComposedApp, composeApp, type TierDefinition, type TierMap, } from "./compose-app.js";
-export { TIER_ENGINE_FEATURE, TierEngineHandlers, TierEngineQueries } from "./constants.js";
+export { TIER_ENGINE_FEATURE, TierAssignmentSources, TierEngineHandlers, TierEngineQueries, } from "./constants.js";
 export { tierAssignmentEntity } from "./entity.js";
 export { type CreateTierEngineOptions, createTierEngineFeature, tierEngineFeature, } from "./feature.js";
 export { createTierResolver, type TierResolver, type TierResolverDeps, } from "./tier-resolver.js";

package/dist/tier-engine/index.js

@@ -8,7 +8,7 @@
 //   - `TierEngineHandlers` / `TierEngineQueries` — qualified handler names
 export { tierAssignmentAggregateId } from "./aggregate-id.js";
 export { composeApp, } from "./compose-app.js";
-export { TIER_ENGINE_FEATURE, TierEngineHandlers, TierEngineQueries } from "./constants.js";
+export { TIER_ENGINE_FEATURE, TierAssignmentSources, TierEngineHandlers, TierEngineQueries, } from "./constants.js";
 export { tierAssignmentEntity } from "./entity.js";
 export { createTierEngineFeature, tierEngineFeature, } from "./feature.js";
 export { createTierResolver, } from "./tier-resolver.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.345.0",
+  "version": "0.346.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -503,12 +503,12 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.345.0",
-    "@cosmicdrift/kumiko-framework": "0.345.0",
-    "@cosmicdrift/kumiko-headless": "0.345.0",
-    "@cosmicdrift/kumiko-renderer": "0.345.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.345.0",
-    "@cosmicdrift/kumiko-types": "0.345.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.346.0",
+    "@cosmicdrift/kumiko-framework": "0.346.0",
+    "@cosmicdrift/kumiko-headless": "0.346.0",
+    "@cosmicdrift/kumiko-renderer": "0.346.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.346.0",
+    "@cosmicdrift/kumiko-types": "0.346.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -1025,8 +1025,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.345.0",
-    "@cosmicdrift/kumiko-locale-es": "0.345.0",
+    "@cosmicdrift/kumiko-locale-de": "0.346.0",
+    "@cosmicdrift/kumiko-locale-es": "0.346.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/audit/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.346.0",
+    "type": "improvement",
+    "title": "Audit queries can read app-instance system events with scope \"system\" (SystemAdmin only)",
+    "detail": "Audit queries accept `scope: \"system\"` for SystemAdmin\n`audit:query:list` and `audit:query:details` take an optional `scope` (`\"tenant\"` or `\"system\"`). With `\"system\"` a SystemAdmin reads the app-instance system events, e.g. `kumiko:system:app.started`; other roles are denied. Without `scope` nothing changes."
+  },
   {
     "version": "0.345.0",
     "type": "fix",

package/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.346.0",
+    "type": "fix",
+    "title": "Subscription webhooks no longer overwrite manual tier grants",
+    "detail": "Subscription tier sync keeps manual tier grants\nThe billing webhook sync now skips tier assignments with `source: \"manual\"`, so a `set-tenant-tier` grant is no longer overwritten by Stripe created/canceled events. Rows the sync writes are marked `source: \"billing\"`. `TierAssignmentSources` is exported from tier-engine."
+  },
   {
     "version": "0.344.0",
     "type": "breaking",

package/src/step-dispatcher/changes.json

@@ -1,4 +1,29 @@
 [
+  {
+    "version": "0.346.0",
+    "type": "fix",
+    "title": "A failed key erase no longer causes a second delivery of the same dispatch request",
+    "detail": "step-dispatcher no longer re-sends after a failed key erase\nWhen erasing the per-dispatch key failed after the outcome was recorded, the redelivered request was sent again and produced a second `step.dispatched`. A redelivery now only repeats the erase."
+  },
+  {
+    "version": "0.346.0",
+    "type": "fix",
+    "title": "Webhook caller headers no longer merge with the default Content-Type or the auth header",
+    "detail": "Webhook headers merge case-insensitively\nA caller `Content-Type` replaces the default `application/json` instead of being joined with it. When a caller header collides with the auth header (any casing), the resolved secret value wins."
+  },
+  {
+    "version": "0.346.0",
+    "type": "fix",
+    "title": "Webhook requests time out after 10 seconds instead of blocking the dispatcher",
+    "detail": "Webhook requests time out after 10 seconds\nA hanging receiver now ends as `step.dispatch-failed` and no longer stalls the step-dispatcher for every tenant."
+  },
+  {
+    "version": "0.346.0",
+    "type": "breaking",
+    "title": "r.step.webhook.send drops the unused retry option",
+    "detail": "`r.step.webhook.send` no longer accepts `retry`\nThe option was never applied: every dispatch request is delivered once. Passing it is now a type error, and the dispatch-requested payload no longer carries it. Stored events that still contain `retry` are parsed and delivered as before.",
+    "migration": "Remove `retry` from `r.step.webhook.send` calls; it was never applied. Each dispatch request is delivered once; a delivery error ends as step.dispatch-failed."
+  },
   {
     "version": "0.345.0",
     "type": "improvement",