Field Approval
Four-eyes approval for a payment-relevant field. The contact entity declares
access: { approve: ["Accountant"] } on iban. A PropertyManager may edit
the contact but cannot change the IBAN directly; a second person with the
Accountant role applies the change.
What it shows
Section titled “What it shows”access.approveon the field — the executor refuses a create or update that changes the field by a user without an approve role: 403 withdetails.reason: "field_approval_required". Unchanged values pass, so a form that resubmits the old IBAN still saves.- Filing the change —
field-approval:query:pending-changeswith anentityTypealso returnsgatedFields: the fields the caller may write but must request (entityId: nullfor a record not created yet). The edit form shows them read-only with “Request change”; its drawer files the changed ones asfield-approval:write:request-changecommands ({ entityType, entityId, fieldName, value }) in one batch, so the form keeps a single Save. The 403 stays as the safety net and shows as a field error. - Deciding —
field-approval:query:pending-changeslists the open requests with their value;approve-changeapplies one,reject-changedeclines it (the requester may withdraw their own). Both pin the requestversion, so a value re-submitted in between is never approved unseen. Whoever filed a request cannot approve it. - Mounting —
createFieldApprovalFeature({ parents: ["contact"] })must list every host entity with an approval-gated field; boot validation fails otherwise. - Encryption — the requested value of a PII field is stored encrypted under the host record’s subject, so forgetting the host makes it unreadable.
Source code
Section titled “Source code”The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):
import { createFieldApprovalFeature } from "@cosmicdrift/kumiko-bundled-features/field-approval";import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
export const contactEntity = createEntity({ name: "contact", table: "read_sample_fa_contacts", fields: { name: createTextField({ required: true, maxLength: 64, personal: false, reason: "technical_reference", }), // Only an Accountant changes the IBAN directly; a PropertyManager files a request instead. iban: createTextField({ maxLength: 34, personal: "self", find: "secret", access: { approve: ["Accountant"], write: ["PropertyManager", "Accountant"] }, }), },});
const roles = ["PropertyManager", "Accountant"] as const;const crudAccess = { access: { roles } } as const;
export const contactFeature = defineFeature("contacts", (r) => { r.crud(contactEntity, { write: crudAccess, read: crudAccess, verbs: { delete: false, list: false, restore: false }, });});
export const fieldApprovalFeature = createFieldApprovalFeature({ parents: ["contact"], roles,});📄 On GitHub: samples/recipes/field-approval/src/feature.ts