Building a form: data model → data binding → write-only secrets
A form is three things, and the platform already has each of them. You wire them together; you build none of them.
The worked example is the setup intake (Hosting.Instance/SetupIntake): a client's IT administrator, a guest with
Editor on one node, answers questions and saves three secrets to the client's own Key Vault.
1. The data model — a typed content record and a NodeType
- The record: one
recordwith a property per answer —Hosting.Instance/SetupIntake/Source/SetupIntakeContent.cs.[Description("…")]+[Translation("de", "…")]on every property: that is the field's label, per viewer language.[Browsable(false)]keeps a property out of the editor;[Editable(false)]states it is not for the viewer to change.- A
boolrenders as a checkbox, anenumas a dropdown, everything scalar else as text. A list or nested record is not offered (it cannot be written back as text — coreMeshNodeEditorField.FromType). - Keep a
[JsonExtensionData]buffer so a field a newer build wrote is not dropped on a round trip. - No secret is a property. Ever.
- The NodeType:
Hosting.Instance/SetupIntake.json—WithContentType<SetupIntakeContent>(), the page asWithNodePage("Overview", …), and aTestsarea. - Where the node lives: decide what a person who may EDIT the content must NOT decide. The setup intake takes its
target record from the node's id (
{space}/SetupIntake/{targetDeployment}), because an editor cannot rename it. - Docs:
get Doc/Architecture/NodeTypeCompilation, skill/layout-area.
2. Data binding — the GUI on the node stream, nothing in between
MeshNodeContentEditorControlover the node's own path, fields from the record in the viewer's locale:new MeshNodeContentEditorControl(path) { CanEdit = mayEdit, Fields = MeshNodeEditorField.FromType(typeof(T), locale) }—Hosting.Instance/SetupIntake/Source/SetupIntakePage.cs(Overview). It reads the node stream and writes each field back through it; whoever may notUpdatethe node sees it read-only (hub.CheckPermission(path, Permission.Update)).- Compose the page from platform controls only:
Controls.Stack,Controls.Markdown,Controls.H3, the editor, andWriteOnlySecretSection(step 3). - Docs:
get Doc/GUI/DataBinding,get Doc/GUI/LayoutAreas, skill/layout-area; another example:Store/BillingProfile/Source/BillingForm.cs.
3. Secrets — from the write-only section straight to Key Vault
- The control: core
src/MeshWeaver.Graph/Configuration/WriteOnlySecretSection.cs— a password box, Save (and Generate, shown once), over a liveSecretStatus(src/MeshWeaver.Mesh.Contract/Security/SecretStatus.cs): present, fingerprint (SecretFingerprint), who and when — never a value. The buffer is cleared the moment it is read. - The verbs are seams, registered by the compiled
Hosting.Instancemodule (src/MeshWeaver.Hosting.Instance/InstanceSecretWriteSeams.cs) as plainFuncs, so node source can call them:- an installation's global administrator → the admin seams (
FileSecretWrite; the Google client setup,Google/Account/Source/GoVaultSetup.cs), for objects its OWN record lists inoperator.selfServiceSecrets, admitted without a second approver; - a guest who may EDIT an intake →
Func<string, string, string, string, IObservable<SecretStatus>>(intake, object, value, reason) and the state seamFunc<string, string, IObservable<(SecretStatus, string, string)>>(InstanceActionRequests.FileGuestSecretWrite), for objects the TARGET record lists inoperator.intakeSecrets, from installations it lists inoperator.intakeFrom— parked for a global administrator's approval.
- an installation's global administrator → the admin seams (
- What happens to the value: sealed in memory to the control instance's public key, bound to
{record}|{object}(coreDoc/Architecture/SecretSealing); posted as a signedinstance-secret-write; the control router (Hosting/Deployment/Source/InstanceSecretWrites.cs) admits it, re-protects it and files ONE governedSetSecretsrun; the writer Job writes the vault object and confirms it from metadata. The plaintext is never on a node, an event or a log. - The record opts in, in the config repository (never by hand on the mesh):
"keyVault": "<vault>",
"keyVaultSecretPrefix": "acme-",
"operator": {
"intakeSecrets": [ "acme-Authentication-Microsoft-ClientSecret", "acme-GitHub-App-PrivateKey", "acme-GitHub-Webhook-Secret" ],
"intakeFrom": [ "<speaking installation's record id>" ]
}
- Docs: core
Doc/Architecture/InstanceSecrets,Doc/Architecture/SecretSealing;Hosting/Guide→ "A GUEST saves a secret for ANOTHER record".
Forbidden — each has already cost someone a day
- A layout area that WAITS on a node stream or a query and builds controls out of the values (the
layout-area-data-bakeratchet reds it): emit the template at once and let the bound controls read the node. - A
/datacopy of the node plus a Save button or an*AutoSavesubscription — two stores drift and the save clobbers fields nobody edited. Bind the editor to the node. - A hand-built
<input>,<table>orControls.Htmlmarkup, or a CSS system of your own. Use the platform's controls; if one is missing, add it to the platform. - A secret as a content property, a secret in a log line, or a status that reads a value back.
.Take(1)on a stream that feeds a live bound view (it freezes the binding);async/awaitin node code.- A target, a vault or a prefix decided by a field the editor can type — derive it from what the editor cannot change.
- A guest admitted unattended, or an allow-list that is not empty by default.