@cosmicdrift/kumiko-framework 0.332.0 → 0.334.0

package/dist/engine/field-access.d.ts

@@ -1,4 +1,6 @@
 import type { EntityDefinition, SessionUser } from "./types/index.js";
+export declare function maskWriteOnlyFields<T extends Readonly<Record<string, unknown>>>(entity: EntityDefinition, row: T): T;
+export declare function dropEmptyWriteOnlyValues<T extends Readonly<Record<string, unknown>>>(entity: EntityDefinition, values: T): T;
 export declare function filterReadFields(entity: EntityDefinition, data: Readonly<Record<string, unknown>>, user: SessionUser): Record<string, unknown>;
 export declare function checkWriteFieldRoles(entity: EntityDefinition, changes: Readonly<Record<string, unknown>>, user: SessionUser): string | null;
 export declare function checkWriteFieldOwnership(entity: EntityDefinition, submittedChanges: Readonly<Record<string, unknown>>, user: SessionUser, oldRow?: Readonly<Record<string, unknown>>, rowContext?: Readonly<Record<string, unknown>>): string | null;

package/dist/engine/field-access.js

@@ -1,4 +1,40 @@
 import { normalizeAccessEntry, userCanReadFieldRow, userCanWriteFieldRow } from "./ownership.js";
+function writeOnlyFieldNames(entity) {
+    const names = [];
+    for (const [name, field] of Object.entries(entity.fields)) {
+        if (field.type === "text" && field.writeOnly === true)
+            names.push(name);
+    }
+    return names;
+}
+function maskWriteOnlyValue(value) {
+    return value === null || value === undefined || value === "" ? null : true;
+}
+// writeOnly text fields never leave the server as plaintext: set -> true,
+// empty -> null. Only keys present in the row are touched (a partial `changes`
+// stays partial). Returns the same object when the entity has no such field.
+export function maskWriteOnlyFields(entity, row) {
+    const names = writeOnlyFieldNames(entity);
+    if (names.length === 0)
+        return row;
+    const masked = { ...row };
+    for (const name of names) {
+        if (name in masked)
+            masked[name] = maskWriteOnlyValue(masked[name]);
+    }
+    return masked; // @cast-boundary engine-payload
+}
+// Write payloads: "" on a writeOnly field means "unchanged" (an untouched
+// masked input submits it), so the key is dropped before the executor sees it.
+export function dropEmptyWriteOnlyValues(entity, values) {
+    const names = writeOnlyFieldNames(entity).filter((name) => values[name] === "");
+    if (names.length === 0)
+        return values;
+    const kept = { ...values };
+    for (const name of names)
+        delete kept[name];
+    return kept; // @cast-boundary engine-payload
+}
 // Field-level read filtering. Returns a copy of `data` with fields stripped
 // if the user's roles don't grant read access OR the ownership-rule for the
 // matching role doesn't accept this concrete row. Fields without access
@@ -22,6 +58,10 @@ export function filterReadFields(entity, data, user) {
         if (!userCanReadFieldRow(user, accessMap, data)) {
             continue; // entire field stripped
         }
+        if (field.type === "text" && field.writeOnly === true) {
+            result[key] = maskWriteOnlyValue(value);
+            continue;
+        }
         // For embedded fields: filter sub-fields with access restrictions.
         // A list-embedded value is an array of rows — each row is filtered on its
         // own, so a sub-field rule can reference the row it sits in. Filtering the

package/dist/engine/index.d.ts

@@ -28,7 +28,7 @@ export { declareEscapeHatch } from "./escape-hatch-declaration.js";
 export type { EmitCtx } from "./event-helpers.js";
 export { emitEvent, typedPayload } from "./event-helpers.js";
 export type { KumikoExtensionName, TenantResourceExtensionName } from "./extension-names.js";
-export { EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_PUBLIC_PREDICATE, EXT_DERIVATIVE_RENDERER, EXT_EXTERNAL_RESOURCE, EXT_FILE_PROVIDER, EXT_INFRA_RESOURCE, EXT_PRINCIPAL_STATUS, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, EXT_USER_DATA, EXT_USER_DATA_ORDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, TENANT_MEMBERSHIPS_QUERY, } from "./extension-names.js";
+export { EXT_ASSIGNABLE_ROLE, EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_PUBLIC_PREDICATE, EXT_DERIVATIVE_RENDERER, EXT_EXTERNAL_RESOURCE, EXT_FILE_PROVIDER, EXT_INFRA_RESOURCE, EXT_PRINCIPAL_STATUS, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, EXT_USER_DATA, EXT_USER_DATA_ORDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, TENANT_MEMBERSHIPS_QUERY, } from "./extension-names.js";
 export { EXTENSION_SELECTOR_HINT_KEY, extensionSelectorTargets, SELECTED_EXTENSIONS_QUERY, selectablePluginIds, } from "./extension-selector-plugins.js";
 export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage.js";
 export type { StorageProviderDestroyTenantHook, StorageProviderExtensionHooks, StorageProviderHookCtx, } from "./extensions/storage-provider.js";
@@ -40,7 +40,7 @@ export type { AddEntityArgs, AddHookArgs, AddRelationArgs, AddWriteHandlerArgs,
 export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, groupByCategory, PATTERN_LIBRARY, parseFeatureFile, parsePatternChanges, parseSourceFile, removePattern, renderFeatureFile, renderPattern, replacePattern, updatePattern, VERSION_HEADER, } from "./feature-ast/index.js";
 export { type ChangelogEntry, type ChangelogType, compareVersions, type FeatureChangelog, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { type BuildManifestOptions, buildManifestFromRegistry, type FeatureManifest, type ManifestConfigKey, type ManifestExtension, type ManifestFeature, type ManifestSecret, serializeManifest, } from "./feature-manifest.js";
-export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, } from "./field-access.js";
+export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 export { buildSessionRoles, findForbiddenMembershipRole, isForbiddenMembershipRole, stripForbiddenMembershipRoles, } from "./membership-roles.js";
@@ -57,7 +57,8 @@ export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
 export type { ClampInfo, ResolveOptions } from "./resolve-config-or-param.js";
 export { resolveConfigOrParam } from "./resolve-config-or-param.js";
-export { findForbiddenRoleAssignment } from "./role-assignment.js";
+export type { AssignableAppRoles, AssignableFromRole } from "./role-assignment.js";
+export { assignableAppRolesFromUsages, findForbiddenRoleAssignment, isAssignableByRole, } from "./role-assignment.js";
 export { runsInLane } from "./run-in.js";
 export type { StepListOutcome } from "./run-pipeline.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";

package/dist/engine/index.js

@@ -26,7 +26,7 @@ export { createEntityExecutor, defineEntityCreateHandler, defineEntityDeleteHand
 defineEntityQueryHandler, defineEntityRestoreHandler, defineEntityUpdateHandler, defineEntityWriteHandler, defineProjectionQueryHandler, entityListSchema, MAX_LIST_LIMIT, registerEntityCrud, } from "./entity-handlers.js";
 export { declareEscapeHatch } from "./escape-hatch-declaration.js";
 export { emitEvent, typedPayload } from "./event-helpers.js";
-export { EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_PUBLIC_PREDICATE, EXT_DERIVATIVE_RENDERER, EXT_EXTERNAL_RESOURCE, EXT_FILE_PROVIDER, EXT_INFRA_RESOURCE, EXT_PRINCIPAL_STATUS, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, EXT_USER_DATA, EXT_USER_DATA_ORDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, TENANT_MEMBERSHIPS_QUERY, } from "./extension-names.js";
+export { EXT_ASSIGNABLE_ROLE, EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_PUBLIC_PREDICATE, EXT_DERIVATIVE_RENDERER, EXT_EXTERNAL_RESOURCE, EXT_FILE_PROVIDER, EXT_INFRA_RESOURCE, EXT_PRINCIPAL_STATUS, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, EXT_USER_DATA, EXT_USER_DATA_ORDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, TENANT_MEMBERSHIPS_QUERY, } from "./extension-names.js";
 export { EXTENSION_SELECTOR_HINT_KEY, extensionSelectorTargets, SELECTED_EXTENSIONS_QUERY, selectablePluginIds, } from "./extension-selector-plugins.js";
 export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage.js";
 export { isTenantDataExtensionHooks, } from "./extensions/tenant-data.js";
@@ -35,7 +35,7 @@ export { createBigIntField, createBooleanField, createDateField, createDecimalFi
 export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, groupByCategory, PATTERN_LIBRARY, parseFeatureFile, parsePatternChanges, parseSourceFile, removePattern, renderFeatureFile, renderPattern, replacePattern, updatePattern, VERSION_HEADER, } from "./feature-ast/index.js";
 export { compareVersions, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { buildManifestFromRegistry, serializeManifest, } from "./feature-manifest.js";
-export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, } from "./field-access.js";
+export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/
@@ -54,7 +54,7 @@ export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.js";
 export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
 export { resolveConfigOrParam } from "./resolve-config-or-param.js";
-export { findForbiddenRoleAssignment } from "./role-assignment.js";
+export { assignableAppRolesFromUsages, findForbiddenRoleAssignment, isAssignableByRole, } from "./role-assignment.js";
 export { runsInLane } from "./run-in.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-builder.js";

package/dist/engine/role-assignment.d.ts

@@ -1 +1,11 @@
-export declare function findForbiddenRoleAssignment(actorRoles: readonly string[], assignedRoles: readonly string[], targetCurrentRoles: readonly string[]): string | undefined;
+export type AssignableFromRole = "User" | "Member" | "Editor" | "Admin" | "TenantAdmin" | "SystemAdmin";
+/** App role → lowest built-in role allowed to assign it. */
+export type AssignableAppRoles = ReadonlyMap<string, AssignableFromRole>;
+export declare const DEFAULT_APP_ROLE_ASSIGNABLE_FROM: AssignableFromRole;
+export declare function assignableAppRolesFromUsages(usages: readonly {
+    entityName: string;
+    options?: Record<string, unknown> | undefined;
+}[]): AssignableAppRoles;
+/** True when `actorRole` ranks at least as high as the role an app role is assignable from. */
+export declare function isAssignableByRole(assignableFrom: AssignableFromRole, actorRole: AssignableFromRole): boolean;
+export declare function findForbiddenRoleAssignment(actorRoles: readonly string[], assignedRoles: readonly string[], targetCurrentRoles: readonly string[], assignableAppRoles?: AssignableAppRoles): string | undefined;

package/dist/engine/role-assignment.js

@@ -1,8 +1,13 @@
+import { ROLES } from "../auth/roles.js";
+import { isForbiddenMembershipRole } from "./membership-roles.js";
+const PLATFORM_ROLE_NAMES = new Set(Object.values(ROLES));
 // Prototype-free rank table — Object literals leak Object.prototype
 // (`constructor`, `toString`, …) into `ROLE_RANKS[role]` lookups and turn
 // Math.max into NaN, which fails every `rank > actorRank` check open.
 const ROLE_RANKS = new Map([
     ["User", 0],
+    // Default seed role — unranked it would fail closed and never be assignable.
+    ["Member", 0],
     // Matches DEFAULT_INVITE_ROLE_OPTIONS — must stay ranked or invite UI fails closed.
     ["Editor", 1],
     ["Admin", 2],
@@ -10,7 +15,55 @@ const ROLE_RANKS = new Map([
     ["SystemAdmin", 4],
     ["system", 5],
 ]);
-// Unknown roles: +∞ on the assigned path (cannot grant what we don't know),
+// App roles are ordinary, non-privileged tiers: whoever may manage members
+// (access.admin) may grant them; an app raises the bar via assignableFrom.
+export const DEFAULT_APP_ROLE_ASSIGNABLE_FROM = "Admin";
+const NO_ASSIGNABLE_APP_ROLES = new Map();
+const ASSIGNABLE_FROM_ROLES = new Set([
+    "User",
+    "Member",
+    "Editor",
+    "Admin",
+    "TenantAdmin",
+    "SystemAdmin",
+]);
+function isAssignableFromRole(value) {
+    return typeof value === "string" && ASSIGNABLE_FROM_ROLES.has(value);
+}
+export function assignableAppRolesFromUsages(usages) {
+    const result = new Map();
+    for (const usage of usages) {
+        const role = usage.entityName;
+        if (role === "") {
+            throw new Error("assignableRole: role name must not be empty");
+        }
+        // Platform roles (TenantOwner, DataProtectionOfficer) gate handlers that
+        // TenantAdmin/Admin cannot reach — declaring one would let an Admin
+        // self-grant it, so they stay out of reach of app declarations.
+        if (ROLE_RANKS.has(role) || PLATFORM_ROLE_NAMES.has(role)) {
+            throw new Error(`assignableRole: "${role}" is a built-in role and cannot be redeclared`);
+        }
+        if (isForbiddenMembershipRole(role)) {
+            throw new Error(`assignableRole: "${role}" is a reserved role and cannot be a membership role`);
+        }
+        const declaredAssignableFrom = usage.options?.["assignableFrom"];
+        if (declaredAssignableFrom !== undefined && !isAssignableFromRole(declaredAssignableFrom)) {
+            throw new Error(`assignableRole: "${role}" has invalid assignableFrom, expected one of ${[...ASSIGNABLE_FROM_ROLES].join(", ")}`);
+        }
+        const assignableFrom = declaredAssignableFrom ?? DEFAULT_APP_ROLE_ASSIGNABLE_FROM;
+        const existing = result.get(role);
+        if (existing !== undefined && existing !== assignableFrom) {
+            throw new Error(`assignableRole: "${role}" is declared with conflicting assignableFrom (${existing} vs ${assignableFrom})`);
+        }
+        result.set(role, assignableFrom);
+    }
+    return result;
+}
+/** True when `actorRole` ranks at least as high as the role an app role is assignable from. */
+export function isAssignableByRole(assignableFrom, actorRole) {
+    return getRoleRank(assignableFrom) <= getRoleRank(actorRole);
+}
+// Unknown roles: +∞ on the assigned path (cannot grant what we don't know, unless declared),
 // -1 on the actor path (cannot elevate via an unrecognized self-role).
 function roleRankOr(role, unknownRank) {
     return ROLE_RANKS.get(role) ?? unknownRank;
@@ -27,15 +80,23 @@ function maxRoleRank(roles) {
 function knownRoleRank(role) {
     return ROLE_RANKS.get(role);
 }
+// Built-ins win: a declaration can never re-tier a built-in role.
+function requiredAssignRank(role, assignableAppRoles) {
+    const builtIn = ROLE_RANKS.get(role);
+    if (builtIn !== undefined)
+        return builtIn;
+    const assignableFrom = assignableAppRoles.get(role);
+    return assignableFrom === undefined ? Number.POSITIVE_INFINITY : getRoleRank(assignableFrom);
+}
 export function findForbiddenRoleAssignment(actorRoles, assignedRoles, 
 // Required so callers cannot accidentally disable the downgrade/
 // takeover guard by omitting the third argument (new users: pass []).
-targetCurrentRoles) {
+targetCurrentRoles, assignableAppRoles = NO_ASSIGNABLE_APP_ROLES) {
     const actorRank = maxRoleRank(actorRoles);
     // Assign path: fail-closed on unknown / above-actor roles — except unranked
     // app roles the target already holds (round-trip restore after strip).
     const forbiddenAssigned = assignedRoles.find((role) => {
-        if (getRoleRank(role) <= actorRank)
+        if (requiredAssignRank(role, assignableAppRoles) <= actorRank)
             return false;
         if (knownRoleRank(role) === undefined && targetCurrentRoles.includes(role))
             return false;

package/dist/engine/schema-builder.d.ts

@@ -3,6 +3,7 @@ import type { EntityDefinition, FieldDefinition } from "./types/index.js";
 export declare function isRepresentableAtScale(n: number, scale: number): boolean;
 export declare function fieldToZod(field: FieldDefinition, currencies: readonly string[], opts?: {
     readonly applyDefaults?: boolean;
+    readonly isUpdate?: boolean;
 }): z.ZodTypeAny;
 export declare function buildInsertSchema(entity: EntityDefinition, currencies?: readonly string[], excludedFields?: readonly string[], options?: {
     readonly allowCallerId?: boolean;

package/dist/engine/schema-builder.js

@@ -87,6 +87,13 @@ export function fieldToZod(field, currencies, opts = {}) {
             let schema = z.string();
             if (field.maxLength)
                 schema = schema.max(field.maxLength);
+            if (field.writeOnly === true) {
+                // Update: "" = unchanged (dropped before the executor), null = clear,
+                // unless required. Create: "" would leave a required field unset.
+                if (opts.isUpdate !== true)
+                    return field.required ? schema.min(1) : schema;
+                return field.required ? schema : schema.nullable();
+            }
             if (field.format === "email")
                 schema = schema.email();
             if (field.format === "url")
@@ -399,7 +406,10 @@ export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES],
         // fieldToZod still knows the default for its "" → default mapping
         // (e.g. select) — applyDefaults: false only suppresses the schema-level
         // `.default(...)` fallback for a genuinely omitted key.
-        shape[name] = fieldToZod(field, currencies, { applyDefaults: false }).optional();
+        shape[name] = fieldToZod(field, currencies, {
+            applyDefaults: false,
+            isUpdate: true,
+        }).optional();
     }
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }

package/dist/engine/types/index.d.ts

@@ -6,7 +6,7 @@ export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap,
 export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsMap, } from "@cosmicdrift/kumiko-types/extension-options-map";
 export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
-export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
+export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
 export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
 export { isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";

package/dist/files/file-ref-entity.d.ts

@@ -9,6 +9,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -29,6 +30,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -49,6 +51,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -81,6 +84,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -101,6 +105,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -121,6 +126,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/files/file-ref-table.d.ts

@@ -9,6 +9,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -29,6 +30,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -49,6 +51,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -81,6 +84,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -101,6 +105,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -121,6 +126,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/i18n/required-surface-keys.js

@@ -42,6 +42,7 @@ function editFieldName(f) {
 // Group titles are translated exactly like the section title (computeEditViewModel).
 function pushSectionTitles(out, section, treatAsKey = false) {
     pushKey(out, section.title, treatAsKey);
+    pushKey(out, section.subtitle, treatAsKey);
     for (const group of section.groups ?? [])
         pushKey(out, group.title, treatAsKey);
 }
@@ -51,6 +52,10 @@ function pushRowActionKeys(out, action) {
         pushKey(out, action.confirm);
         pushKey(out, action.confirmLabel);
     }
+    if (action.kind === "drawer") {
+        pushKey(out, action.title);
+        pushKey(out, action.subtitle);
+    }
 }
 function pushDashboardScreenKeys(out, dashboard) {
     for (const panel of dashboard.panels)
@@ -103,9 +108,12 @@ function pushToolbarActionKeys(out, action) {
         pushKey(out, action.confirm);
         pushKey(out, action.confirmLabel);
     }
-    // drawer-kind carries no confirm/confirmLabel — action.label (the
-    // toolbar button AND the Drawer title, see ToolbarDrawerHost) is
-    // already pushed above.
+    // drawer-kind carries no confirm/confirmLabel — action.label is the
+    // toolbar button and the Drawer title unless `title` overrides it.
+    if (action.kind === "drawer") {
+        pushKey(out, action.title);
+        pushKey(out, action.subtitle);
+    }
 }
 function pushRelatedListSectionKeys(out, section) {
     pushKey(out, section.title);
@@ -180,6 +188,7 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
         case "entityEdit": {
             const edit = screen;
             pushKey(out, edit.submitLabel);
+            pushKey(out, edit.titleTemplate);
             for (const section of edit.layout.sections) {
                 if (isExtensionEditSection(section)) {
                     pushKey(out, section.title);
@@ -204,6 +213,8 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
             pushKey(out, form.submitLabel);
             pushKey(out, form.summary?.title);
             pushKey(out, form.summary?.subtitle);
+            for (const action of form.footerActions ?? [])
+                pushKey(out, action.label);
             for (const fieldName of Object.keys(form.fields)) {
                 const override = form.fieldLabels?.[fieldName];
                 if (override !== undefined)
@@ -282,6 +293,10 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
         case "configEdit": {
             const config = screen;
             pushKey(out, config.submitLabel);
+            pushKey(out, config.description, treatDotFormAsKey);
+            for (const key of Object.values(config.fieldDescriptions ?? {})) {
+                pushKey(out, key, treatDotFormAsKey);
+            }
             for (const fieldName of Object.keys(config.fields)) {
                 const override = config.fieldLabels?.[fieldName];
                 if (override !== undefined)
@@ -297,6 +312,7 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                 if (section.kind === "relatedList")
                     continue; // rejected at boot, unreachable here
                 pushSectionTitles(out, section, treatDotFormAsKey);
+                pushKey(out, section.description, treatDotFormAsKey);
                 for (const f of sectionFieldSpecs(section)) {
                     const fieldName = editFieldName(f);
                     const override = config.fieldLabels?.[fieldName];
@@ -328,6 +344,11 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                 }
                 if (section.kind === "relatedList") {
                     pushRelatedListSectionKeys(out, section);
+                    if (section.groupBy !== undefined) {
+                        pushKey(out, section.groupBy.label);
+                        for (const label of Object.values(section.groupBy.labels ?? {}))
+                            pushKey(out, label);
+                    }
                     continue;
                 }
                 if (isWriteFormEditSection(section)) {

package/dist/i18n/settings-hub-keys.js

@@ -16,14 +16,28 @@ export const SETTINGS_HUB_I18N = {
     "config.settings.tenant": { en: "Tenant" },
     "config.settings.user": { en: "Personal" },
     "config.settings.extensionSelectorHint": {
-        en: "Save the provider selection to show its settings below.",
+        en: "Choose a provider and save. Its settings appear below.",
     },
+    "config.settings.provider": { en: "Provider" },
+    "config.settings.saveProvider": { en: "Save provider" },
+    "config.settings.audience.system": {
+        en: "Applies to every tenant unless a tenant sets its own value.",
+    },
+    "config.settings.audience.tenant": {
+        en: "Applies to everyone in this tenant. Platform defaults are shown where nothing is set here.",
+    },
+    "config.settings.audience.user": { en: "Only applies to you." },
     "config.secrets.title": { en: "Secrets" },
     "config.secrets.notSet": { en: "Not set" },
     "config.secrets.set": { en: "Set" },
-    "config.secrets.required": { en: "Required" },
+    "config.secrets.saved": { en: "Saved" },
+    "config.secrets.section": { en: "Secrets" },
+    "config.secrets.description": {
+        en: "Stored encrypted. Saved values are never shown again.",
+    },
+    "config.secrets.stored": { en: "Stored: {preview}" },
     "config.secrets.placeholder": { en: "Enter a value" },
-    "config.secrets.replacePlaceholder": { en: "Enter a new value to replace" },
-    "config.secrets.delete": { en: "Delete" },
+    "config.secrets.replacePlaceholder": { en: "Enter a new value to replace it" },
+    "config.secrets.delete": { en: "Remove" },
     "screen:secrets.title": { en: "Secrets" },
 };

package/dist/pipeline/dispatch-batch.js

@@ -7,6 +7,7 @@ import { resolveDbSource } from "./dispatch-shared.js";
 import { executeNestedWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
 import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin.js";
+import { maskBatchResultForClient } from "./write-result-masking.js";
 // afterCommit hooks fire in flushAfterCommit, outside the command's scope.
 function rewrapHooksWithOrigin(afterCommitHooks, fromIndex, origin) {
     for (let i = fromIndex; i < afterCommitHooks.length; i++) {
@@ -51,20 +52,24 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
             idempotencyToken = checked.token;
         }
     }
+    // Hooks already ran on the plaintext results; what is returned and cached
+    // for retries must not carry writeOnly values.
+    const maskForClient = (result) => maskBatchResultForClient(ctx.registry, commands, result);
     // Cache the result under requestId so retries get the same answer. Only a
     // provably rolled-back 5xx releases the lock instead (releaseOrFinalize).
     const finalize = async (result) => {
+        const masked = maskForClient(result);
         if (requestId && idempotency && idempotencyToken) {
-            await idempotency.store(user.tenantId, user.id, requestId, idempotencyToken, result);
+            await idempotency.store(user.tenantId, user.id, requestId, idempotencyToken, masked);
         }
-        return result;
+        return masked;
     };
     // Never for the no-tx fallback: without a rollback, a re-run would repeat
     // the side effects of the commands that already ran.
     const releaseOrFinalize = async (result, isRetryableRollback) => {
         if (isRetryableRollback && requestId && idempotency && idempotencyToken) {
             await idempotency.release(user.tenantId, user.id, requestId, idempotencyToken);
-            return result;
+            return maskForClient(result);
         }
         return finalize(result);
     };

package/dist/pipeline/dispatch-write.js

@@ -5,7 +5,7 @@ import { createTenantDb, hasTenantColumn } from "../db/tenant-db.js";
 import { tenantDbRunner } from "../db/tenant-db-runner.js";
 import { hasAccess } from "../engine/access.js";
 import { ConfigScopes } from "../engine/constants.js";
-import { checkWriteFieldOwnership, checkWriteFieldRoles } from "../engine/field-access.js";
+import { checkWriteFieldOwnership, checkWriteFieldRoles, maskWriteOnlyFields, } from "../engine/field-access.js";
 import { defineTransitions, guardTransition } from "../engine/state-machine.js";
 import { HookPhases } from "../engine/types/index.js";
 import { runValidation } from "../engine/validation.js";
@@ -262,7 +262,10 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
             }
             const subWrapper = subResult.data; // @cast-boundary engine-payload
             const subRow = (subWrapper["data"] ?? subWrapper); // @cast-boundary engine-payload
-            subRows.push(subRow);
+            const subEntityName = registry.getHandlerEntity(spec.subType);
+            const subEntity = subEntityName ? registry.getEntity(subEntityName) : undefined;
+            // parentRow is returned to the client; the child's own SaveContext keeps the plaintext.
+            subRows.push(subEntity ? maskWriteOnlyFields(subEntity, subRow) : subRow);
         }
         parentRow[spec.key] = subRows;
     }

package/dist/pipeline/dispatcher-utils.js

@@ -4,8 +4,11 @@ import { VersionConflictError as EventStoreVersionConflictError } from "../event
 export function isFailedWriteResult(result) {
     return (!!result && typeof result === "object" && "isSuccess" in result && result.isSuccess === false);
 }
+const LIFECYCLE_KINDS = ["save", "delete"];
 export function isLifecycleResult(data) {
-    return !!data && typeof data === "object" && "kind" in data;
+    if (!data || typeof data !== "object" || !("kind" in data))
+        return false;
+    return LIFECYCLE_KINDS.some((kind) => kind === data.kind);
 }
 export function isWriteResultShape(result) {
     return (!!result &&

package/dist/pipeline/write-result-masking.d.ts

@@ -0,0 +1,6 @@
+import type { WriteResult } from "../engine/types/index.js";
+import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared.js";
+type EntityLookup = Pick<DispatchContext["registry"], "getHandlerEntity" | "getEntity">;
+export declare function maskWriteResultForClient(registry: EntityLookup, handlerType: string, result: WriteResult): WriteResult;
+export declare function maskBatchResultForClient(registry: EntityLookup, commands: readonly BatchCommand[], batch: BatchResult): BatchResult;
+export {};

package/dist/pipeline/write-result-masking.js

@@ -0,0 +1,36 @@
+import { maskWriteOnlyFields } from "../engine/field-access.js";
+import { isLifecycleResult } from "./dispatcher-utils.js";
+function maskLifecycleOrRow(entity, data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return data;
+    if (!isLifecycleResult(data))
+        return maskWriteOnlyFields(entity, data); // @cast-boundary engine-payload
+    if (data.kind === "save") {
+        return {
+            ...data,
+            data: maskWriteOnlyFields(entity, data.data),
+            changes: maskWriteOnlyFields(entity, data.changes),
+            previous: maskWriteOnlyFields(entity, data.previous),
+        };
+    }
+    return { ...data, data: maskWriteOnlyFields(entity, data.data) };
+}
+// Copy-on-mask: the original results still feed postSaveBatch hooks, which
+// need the plaintext. Only what leaves the dispatcher is masked.
+export function maskWriteResultForClient(registry, handlerType, result) {
+    if (!result.isSuccess)
+        return result;
+    const entityName = registry.getHandlerEntity(handlerType);
+    const entity = entityName ? registry.getEntity(entityName) : undefined;
+    if (!entity)
+        return result;
+    const data = maskLifecycleOrRow(entity, result.data);
+    return data === result.data ? result : { ...result, data };
+}
+export function maskBatchResultForClient(registry, commands, batch) {
+    const results = batch.results.map((result, index) => {
+        const command = commands[index];
+        return command ? maskWriteResultForClient(registry, command.type, result) : result;
+    });
+    return { ...batch, results };
+}