Sensitive fields

What you will take away from this lesson

A supplier’s federal tax ID is needed by exactly one team, once, to set up payments. Everyone else who reads the applications (the category buyers, the regional managers, an analyst asking the agent which categories draw the most interest) has no reason to see it. The supplier form marks that one field sensitive.

Learning Objectives

01Mark a field sensitive and say where its value is encrypted.
02Name the two places it is read in clear and who may read it there.
03Explain why every read is audited and what the audit row names.
04Export submissions to CSV or Excel.
05State why a file field cannot be sensitive, and where its files are kept.

Where this lesson sits

Lessons 703 and 704 built the supplier form and put it in front of the public. This lesson follows its one private field.

700 Series: Endpoints and Forms

Open index

The 700 series builds on the automations of the 600 series: an endpoint is an automation that answers a request, and a form is an endpoint that people fill in.

Marking a field sensitive

The agent marked the tax ID sensitive because the prompt asked for it to be kept private.

One field, marked sensitive

{"name": "tax_id", "type": "text", "label": "Federal tax ID (EIN)",
 "help": "Encrypted when stored. Only the vendor team can read it.",
 "required": True, "max_length": 10, "sensitive": True}

One key in the spec. The form’s automation is still handed the value as typed, so form_submit can check its shape; it is encrypted after that and before anything is written.

Where it is encrypted

The value is encrypted once, before the submission is written, so no stored copy ever holds it in clear.

Where the value is ciphertext

The arrival file: The file a submission is first written to on the server.
The raw events: The submission as the source first stores it.
The compacted files: The tidy files each window of submissions becomes.
The table: Every query of webhook_form_supplier_onboarding, by the agent, an automation, or an analyst, returns ciphertext.

Each value is sealed to its form and its field. A value copied from this form into another, or into a different field, or any other ciphertext the platform holds, such as a stored secret, is refused when someone tries to open it as this form’s.

Querying the table

The table is open to anyone granted its connection, and that is safe because the field is ciphertext in it.

What a query of the table returns

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ trino_query
  SELECT json_extract_scalar(payload, '$.values.company_name') AS company,
         json_extract_scalar(payload, '$.values.tax_id')       AS tax_id_stored
  FROM scratch.uploads.webhook_form_supplier_onboarding LIMIT 2

← company                   tax_id_stored
  Brightleaf Tea Company    encb:iuDbLfC7zeD/a4TlKFiesthuSvN…
  Summit Trail Outfitters   encb:/m1DoqxCCX/7YN2AZ+el7aHCjt…

The agent was asked, as an administrator, to show the stored tax IDs. Being an administrator does not change what the table holds.

Who reads it in clear

There are two places a sensitive value is opened, and each read is on the record.

Where the value is read in clear

The Submissions section owner and administrators: On the form’s automation page in the portal, the newest submissions with sensitive fields decrypted and each file linked, and an export of all of them to CSV or Excel.
An automation, by name platform.decrypt(form, payload): A script whose run presents a persona the form lists in its decrypt personas, set on the binding. The supplier form lists the administrator persona only, so a script saved by an administrator can open the tax ID and a script saved by an analyst is refused.

Each read writes an audit row of kind form_decrypt naming the fields read and who read them, whether it was a person opening Submissions, an export, or a script. There is no third place.

The Submissions section of a form's automation page: Refresh, Export CSV and Export Excel buttons, the scratch table the submissions are stored in, and six rows with received time, company, contact email, category, stores, a tax ID column marked with a lock and shown in clear to the owner, and a link to each uploaded W-9 with its size. — The Submissions view. The lock on a column marks a sensitive field, shown in clear here because the viewer may read it.

Exporting submissions

The vendor team works the applications in a spreadsheet. The Submissions section exports them, sensitive fields included, to CSV or Excel.

Submissions exported to CSV, one row (some columns)

company_name: Northfield Paper Goods
contact_email: [email protected]
category, pilot_store: 18, 254 (the values submitted: a category id and a store id)
annual_volume_usd: 350000
tax_id: 58-2531970, in clear (a fictional value on the demo tenant)
insurance_certificate: certificate-of-insurance.pdf, with its address in the form source’s library
agree_terms: true

The export carries every declared field in the spec’s order, the tax ID in clear, each file as its name and its address in the library, and the submitter on a form that requires sign-in. Choice fields export the value submitted.

A cell a spreadsheet would read as a formula is written with a leading apostrophe, so an application cannot plant a formula in the vendor team’s workbook.

Where it never appears

The places a value could leak by accident (a recording, an error, a notification) hold a marker instead.

Where the value never appears

1
Recordings and tests
A draft or run that decrypts records [encrypted] in place of each value, so no recording, replay, or test holds one.
2
Failed requests
A submission that failed is kept for the owner with each sensitive value replaced by [REDACTED:tax_id], so an error that repeats what it choked on never stores it.
3
The intake post
The automation that runs per application (706) never decrypts. Its post to the operations feed says only that the tax ID was received, encrypted.

File fields

Where the files are kept

Where each certificate is kept

library: The form source’s library, an administrator’s unless the source names a persona.
folder: webhooks/form-supplier-onboarding/attachments/<date>/<submission>/insurance_certificate/
removed with: The source. Deleting the form’s source removes its files.

Next: from submission to action

Key terms

Four terms cover how a sensitive field is kept and read.

Key Terms

Sensitive field: A form field encrypted before it is stored, so every stored copy and every query holds ciphertext.
Decrypt personas: The personas a form lets scripts decrypt its sensitive fields as. Administrators always may.
Submissions: The section on a form’s automation page showing submissions in clear, with CSV and Excel export, for the owner and administrators.
form_decrypt: The audit event every clear read writes, naming the fields and the reader.

705 - Sensitive fields