Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Gateway window: string safety

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.

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.

Was this page helpful?