---
title: "Gateway window: string safety"
description: "How strings in Admin events are kept safe: no string from an Admin event crosses admission, storage, the Unix socket, Tauri IPC or export without the canonical sensitive-text policy."
type: "living"
source: "docs/admin-event-string-safety.md"
verified: "2026-11-14"
group: "Frontends"
---

> **Living doc**, checked against the code 2026-11-14

## Central invariant

No string from an Admin event crosses admission, storage, Unix-socket serialization, or user export without the
canonical sensitive-text policy.

The policy applies recursively to every serialized string value and every dynamic object key. It is not a field
allowlist. A new string, optional string, collection, map or nested object in the event schema is unsafe until it
passes the same traversal. Known identifier fields also have bounded portable grammars. That check is added to the
sensitive-text screen; it never replaces it.

Defense in depth is mandatory:

1. Admission rejects an unsafe or malformed event before deduplication or storage.
2. Every event export boundary screens again. Unsafe legacy, deserialized, test-injected, or otherwise bypassed values are replaced with a non-sensitive representation; malformed structures that cannot be traversed or represented within bounds fail closed.
3. Safe values remain byte-for-byte unchanged. Safe opaque identifiers retain normal equality and correlation behavior. When an unsafe identifier is encountered only at export, use per-export opaque aliases so equal unsafe inputs remain correlated within that export without exposing or hashing low-entropy source text.

Do not sanitize only `message` and `repair_action`. Do not replace the whole event when single fields can be made
safe. Do not trust TypeScript types at runtime.

## Present schema inventory

`AdminEventRecord` exports these string-bearing values:

| Field | Shape | Additional rule |
| --- | --- | --- |
| `event_id` | required string | nonempty, at most 128 bytes, portable opaque identifier grammar, sensitive-text policy |
| `component_id` | required string | nonempty, at most 128 bytes, portable component identifier grammar, sensitive-text policy |
| `continuity_id` | optional string | when present, nonempty, at most 128 bytes, portable opaque identifier grammar, sensitive-text policy |
| `operation_id` | optional string | when present, nonempty, at most 128 bytes, portable opaque identifier grammar, sensitive-text policy |
| `phase` | required string | nonempty, at most 64 bytes, portable phase identifier grammar, sensitive-text policy |
| `message` | required string | nonempty, at most 512 bytes, sensitive-text policy |
| `repair_action` | optional string | when present, nonempty and at most 512 bytes, sensitive-text policy |
| `frame` | optional string, omitted when absent | a bare JPEG name in the Admin socket's `frames/` (camera line snapshots); admission rejects an event whose `frame` `camera_frames::frame_file_is_safe` refuses, and export again keeps it only when that check accepts it and otherwise drops it (never redacts) |
| `channel` | optional object, omitted when absent | closed words only: `kind` (`overlay`, `vigil`, `satellite`), `role` (`full`, `mic`, `speaker`, `ui`), `source` (`mic`, `inject`, `text`), and an optional `room` label of 1 to 32 letters, digits, `-`, `_` or spaces (`admin_channel_is_safe`); admission rejects any other channel and export drops it |

The recursive export traversal also covers the enum strings of `severity`, `recoverability` and `outcome`, JSON
object keys, and any future nested or optional strings. These fields carry no strings: `observation_generation`,
`observed_at_ms`, `persistent`, `projection_generation`, and `truncated`.

`AdminEventSnapshot` also carries optional windows beside the events: `dictation`, `last_minutes`,
`operator_affect`, `ambient_note`, `speaker_enrollment` and `brain`. They are not event records and never pass
`AdminEventStore::record`. They hold counts, closed words and ids; `last_minutes` holds a meeting `call_id`.

`validate_admin_response` bounds them: a `call_id` must be 1..=128 printable ASCII bytes. Only the export traversals
below screen their strings for sensitive text.

The generated `packages/protocol/src/generated/AdminEventRecord.ts` and `AdminEventSnapshot.ts` mirror this schema
but do no runtime validation.

## Implemented path and defense inventory

Admission and storage:

- `crates/protocol/src/lib.rs::AdminEventRecord` defines the wire/storage shape.
- `crates/voice_gateway/src/admin.rs::AdminEventStore::record` calls `validate_admin_event` and stores accepted records in the in-memory `VecDeque`.
- `crates/admin_markers/src/bounds/sanitize.rs::validate_admin_event` (re-exported by `crates/voice_gateway/src/admin/sanitize.rs`) applies portable identifier grammar and bounds to all identifier/phase fields, rejects an empty present `repair_action`, applies the sensitive-text policy to every current string field except `frame` and `channel`, rejects a `frame` that is not a bare camera frame file name (`frame_file_is_safe`), and rejects a `channel` that is not closed words and a room label.
- Accepted records are also appended to the on-disk events tail (`crates/voice_gateway/src/admin_tail.rs`); at start the newest are reloaded through the same `record` validation. `persistent` controls retention semantics, not whether a record reaches the tail.

Gateway export:

- `AdminEventStore::safe_snapshot` aliases unsafe identifiers per export, redacts unsafe prose and drops a `frame` or a `channel` that fails its check before `GetEvents` returns.
- `crates/voice_gateway/src/admin/socket.rs::handle_admin_stream` additionally traverses the complete serialized response, including arrays, unknown future values, and dynamic keys, immediately before Unix-socket serialization.
- `crates/admin_markers/src/client.rs::request_admin_inner` validates the typed Admin response and its Admin protocol version (`crates/admin_markers/src/bounds/response.rs::validate_admin_response`) before returning it.

The Gateway window reads `crates/admin_core` in process. Its user export, the Errors section's "Export redacted
JSON" (`apps/admin-shadow/src/panels/errors_export.rs`), screens every string and key again through the same gate
and holds at most 64 KiB, dropping the oldest non-persistent event first.


The owner-only socket and UI escaping add containment. Neither replaces these content checks.

## Defense ownership and evolution

The Gateway is the authoritative admission and egress boundary. Its typed admission validator rejects unsafe event
records. Its final traversal of the serialized value screens arrays, optional values, object keys, string leaves and
future fields before bytes reach the socket.

Encoded-text normalization uses a deduplicated, bounded fixed-point work queue. Every candidate is checked and
expanded through:

- percent decoding;
- complete HTML entity decoding;
- standard and URL-safe Base64, padded and unpadded;
- punctuation-delimited Base64 windows with arbitrary whitespace.

Bounds on input, unique candidates, folded runs and transform work fail closed. Unexamined text is never treated as
safe.


Generated TypeScript types give shape, not runtime validation. A schema change updates the Gateway policy and the
cross-boundary behavior corpus together. Unsupported values, deep nesting, large collections, oversized strings, or
an unsafe key that cannot be represented cause a fixed non-sensitive error. Rejected text is never interpolated.

## Sensitive classes and expected behavior

At admission, any match below rejects the whole event with a fixed error. At an export boundary, the affected string
is replaced: unsafe identifiers get per-export opaque aliases, other text becomes `[redacted]`. The complete
serialized output never holds the original bytes, the normalized equivalents the policy recognizes, or rejected
values in error messages.

- Credentials and authentication material: authorization values, bearer/basic credentials, cookies and set-cookie
  values, passwords, secrets, tokens, API-key spellings, and recognized encoded or embedded variants. Safe prose next
  to an unrelated field stays unchanged.
- Private filesystem paths: absolute user/private paths such as `/Users/...`, `/home/...`, `~...`, Windows drive/user
  paths, and UNC-style paths. Safe opaque component names such as `speech.tts` stay unchanged.
- URLs: query and fragment data are never exported. A string with a URL query or fragment is replaced as a unit, so
  no part of a credential-bearing URL is copied. No URL field is exempt.
- Headers: request/response header text, especially `Authorization`, `Cookie`, `Set-Cookie`, proxy authorization,
  and API-key headers, in any case and with any surrounding safe text.
- HTML-like payloads: markup/script-like text and its policy-recognized escaped or embedded forms. UI escaping does
  not count as content redaction.
- Mixed content: a string with both safe and sensitive text is replaced whole. No prefix or suffix is kept.
- Optional values: `null` stays `null`. A present string is processed like a required string.
- Nested and future values: strings in arrays and objects, and dynamic keys, are processed recursively. No unknown
  string is copied because the current Rust or TypeScript type did not name it.

