Sensitive Field Audit Masking

TeaQL can mark sensitive fields at the model level so audit-safe runtime events do not expose raw sensitive values to downstream audit consumers.

This is important for privacy and compliance because audit logs are often read by more people and systems than the original business data. A runtime may need to record that a field changed, who changed it, and why, without showing the full password, token, passport number, account number, or personal identifier.

Model-Level Masking

Use _audit_mask_fields on an entity to declare which fields should be masked when TeaQL builds safe audit events.

Example:

<customer
  _name="Customer"
  name="string()"
  email="string()"
  phone="string()"
  passport_number="string()"
  _audit_mask_fields="email,phone,passport_number" />

The model remains the source of truth. Generated code carries the masking metadata into the runtime layer, so application code does not need to remember to mask these fields manually in every service.

Generator Evaluation

TeaQL generation/evaluation can detect likely sensitive fields and report them before runtime.

The current privacy audit rule classifies field names by keyword:

Severity	Example field keywords	Result
High sensitivity	password, token, secret, ssn, passport, cvv, creditcard	Error: masking is required.
PII warning	phone, mobile, email, address, bank, account, health, birth	Warning: masking is strongly recommended.
Personal data suggestion	name, gender, age, ip, device, message	Suggestion: consider masking.

When a field is flagged, the report suggests adding _audit_mask_fields to the entity.

Runtime Behavior

In the Rust runtime path, generated entity metadata is carried into the entity descriptor. When the runtime sends a safe audit event, it reads the descriptor and applies:

• _audit_mask_fields: masks configured field values.
• _audit_value_max_len: limits audit output length when configured.

The safe audit event can still show useful compliance metadata:

• field name,
• whether the field was masked,
• whether the value was truncated,
• raw value length,
• output value length,
• mask reason,
• truncate reason.

This makes audit output reviewable without exposing the full sensitive value.

Masking Shape

The runtime masking behavior is intentionally simple and predictable:

• Empty values stay empty.
• Numeric values are fully replaced with *.
• Short values are fully replaced with *.
• Longer non-numeric values keep a small prefix and suffix while masking the middle.

The exact masking output is for audit safety, not for reversible encryption.

What This Protects

Audit masking helps reduce exposure in:

• operational audit streams,
• support-facing audit views,
• compliance review exports,
• observability pipelines,
• event sinks that should not receive raw PII or secrets.

It is especially useful for fields such as:

• passwords and secrets,
• API tokens and JWTs,
• passport or ID-card numbers,
• payment card references,
• phone numbers,
• email addresses,
• bank account identifiers,
• health or birth-date fields.

What This Does Not Replace

Audit masking is not a complete privacy program by itself.

It does not replace:

• database encryption,
• column-level database permissions,
• authorization checks,
• field-level read policies,
• consent management,
• retention and deletion rules,
• data residency controls,
• secrets management.

Use it as one layer in a broader privacy architecture: model the sensitive field, restrict who can read it, audit why it was accessed, and mask it when it appears in audit-safe event output.

Recommended Rules

1. Mark known sensitive fields with _audit_mask_fields.
2. Treat high-sensitivity generation errors as blocking issues.
3. Review warnings for PII fields before approving the model.
4. Configure _audit_value_max_len when audit output could contain long free text.
5. Keep raw evidence and raw sensitive values out of support-facing audit exports.
6. Do not rely on application developers to manually mask every audit event.
7. Confirm whether each audit sink receives raw audit events or safe audit events.

Review Checklist

Before approving a model with personal or sensitive data, check:

• Are passwords, tokens, government identifiers, card references, and secrets listed in _audit_mask_fields?
• Are phone, email, address, bank, health, and birth-date fields reviewed?
• Does generation/evaluation report any privacy masking errors or warnings?
• Does the runtime route external audit consumers to safe audit events?
• Are long text fields truncated for audit output when needed?
• Do compliance exports avoid raw sensitive values unless explicitly authorized?