mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-17 04:04:25 +00:00
MailCraft crates/jmap's protocol core at a44a450, moved as it is with all its tests: session, requests with result references, responses, ids, addresses and templates, credentials, retry and the judgement of HTTP answers, over any HttpExchange. The mail client on top stays in MailCraft. Co-authored-by: Martin Ball <98639962+benandez@users.noreply.github.com>
286 lines
11 KiB
Rust
286 lines
11 KiB
Rust
//! Making a server's text fit for an error message (requirement 3.5).
|
||
//!
|
||
//! An [`Excerpt`] is one line, without control or invisible characters, at most [`EXCERPT_MAX_CHARS`]
|
||
//! characters, and with every secret the [`Redactor`] knows replaced by `[redacted]`.
|
||
//!
|
||
//! How it works, and why:
|
||
//!
|
||
//! 1. The server's text is first *normalised*: every run of white space, control characters and line or
|
||
//! paragraph separators becomes one space, and invisible formatting characters (zero-width spaces and
|
||
//! joiners, bidirectional controls, the byte order mark, soft hyphens, tag characters) are removed. Secrets
|
||
//! are normalised the same way. Matching happens on the normalised text, which is also what is shown, so
|
||
//! the cleaning cannot rebuild a secret the matching missed (`open\nsesame` is found as `open sesame`).
|
||
//! 2. Matching ignores ASCII case and covers several written forms of each secret (as is, percent-encoded,
|
||
//! form-encoded with `+` for spaces; the credentials add their base64 forms). Overlapping matches are
|
||
//! merged. The search is linear in the text (Knuth–Morris–Pratt), so a hostile server cannot make it slow.
|
||
//! 3. Secrets are replaced before anything is cut: the scanned window reaches past its end by the length of
|
||
//! the longest secret, so a secret straddling the cut is still found whole and never shows half of itself.
|
||
//!
|
||
//! Two strengths of entry: [`Redactor::add`] is for secrets proper (passwords, tokens). When one is shorter
|
||
//! than [`MIN_SECRET_LEN`] octets, replacing it would itself reveal it (every `a` gone tells that the password
|
||
//! is `a`), so all server text is then withheld. [`Redactor::add_personal`] is for personal data and
|
||
//! addresses (a user name, an account name, the session address); a form shorter than [`MIN_SECRET_LEN`] is
|
||
//! then simply not looked for, so that a server cannot blank every message by naming a user `x`.
|
||
|
||
use std::fmt;
|
||
|
||
use crate::credentials::Secret;
|
||
use crate::percent::encode_component;
|
||
|
||
/// The most characters an excerpt holds, not counting the final ellipsis.
|
||
pub const EXCERPT_MAX_CHARS: usize = 160;
|
||
/// Secrets shorter than this, in octets once normalised, cannot be replaced safely.
|
||
pub const MIN_SECRET_LEN: usize = 3;
|
||
/// How much normalised text is looked at, in octets; the rest is cut.
|
||
const SCAN_WINDOW: usize = 4 * 1024;
|
||
/// What replaces a secret.
|
||
const MARK: &str = "[redacted]";
|
||
/// What stands for a text that could not be shown safely.
|
||
const WITHHELD: &str = "[server text withheld]";
|
||
/// The number of characters of [`MARK`].
|
||
const MARK_CHARS: usize = 10;
|
||
|
||
/// A short, single-line, control-free piece of server text with secrets removed.
|
||
#[derive(Clone, PartialEq, Eq, Hash)]
|
||
pub struct Excerpt(String);
|
||
|
||
impl Excerpt {
|
||
/// The text.
|
||
pub fn as_str(&self) -> &str {
|
||
&self.0
|
||
}
|
||
}
|
||
|
||
impl fmt::Display for Excerpt {
|
||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||
f.write_str(&self.0)
|
||
}
|
||
}
|
||
|
||
impl fmt::Debug for Excerpt {
|
||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||
fmt::Debug::fmt(&self.0, f)
|
||
}
|
||
}
|
||
|
||
/// The secrets a client knows, and the means to keep them out of messages.
|
||
#[derive(Clone, Default)]
|
||
pub struct Redactor {
|
||
needles: Vec<Secret>,
|
||
withhold: bool,
|
||
}
|
||
|
||
impl fmt::Debug for Redactor {
|
||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||
write!(f, "Redactor({} forms)", self.needles.len())
|
||
}
|
||
}
|
||
|
||
/// Characters removed outright: they are invisible and could split a secret without showing.
|
||
fn is_invisible(c: char) -> bool {
|
||
matches!(c,
|
||
'\u{00AD}' | '\u{034F}' | '\u{061C}' | '\u{115F}' | '\u{1160}' | '\u{17B4}' | '\u{17B5}' | '\u{180B}'..='\u{180F}'
|
||
| '\u{200B}'..='\u{200F}' | '\u{202A}'..='\u{202E}' | '\u{2060}'..='\u{206F}' | '\u{3164}' | '\u{FE00}'..='\u{FE0F}'
|
||
| '\u{FEFF}' | '\u{FFA0}' | '\u{FFF0}'..='\u{FFFB}' | '\u{E0000}'..='\u{E0FFF}')
|
||
}
|
||
|
||
/// Characters that become a space: white space, controls (Unicode `Cc`), line and paragraph separators.
|
||
fn is_separator(c: char) -> bool {
|
||
c.is_whitespace() || c.is_control() || matches!(c, '\u{2028}' | '\u{2029}')
|
||
}
|
||
|
||
/// Normalises `text` (see the module documentation), stopping once `limit` octets are produced. Returns the
|
||
/// text and whether anything visible was left out.
|
||
fn normalise(text: &str, limit: usize) -> (String, bool) {
|
||
let mut out = String::new();
|
||
let mut pending_space = false;
|
||
for c in text.chars() {
|
||
if is_invisible(c) {
|
||
continue;
|
||
}
|
||
if is_separator(c) {
|
||
pending_space = true;
|
||
continue;
|
||
}
|
||
if out.len().saturating_add(c.len_utf8()).saturating_add(1) > limit {
|
||
return (out, true);
|
||
}
|
||
if pending_space && !out.is_empty() {
|
||
out.push(' ');
|
||
}
|
||
pending_space = false;
|
||
out.push(c);
|
||
}
|
||
(out, false)
|
||
}
|
||
|
||
fn floor_boundary(text: &str, index: usize) -> usize {
|
||
let mut index = index.min(text.len());
|
||
while index > 0 && !text.is_char_boundary(index) {
|
||
index = index.saturating_sub(1);
|
||
}
|
||
index
|
||
}
|
||
|
||
/// The Knuth–Morris–Pratt failure table: for each prefix of `needle`, the length of its longest proper
|
||
/// prefix that is also a suffix.
|
||
fn failure_table(needle: &[u8]) -> Vec<usize> {
|
||
let mut table = vec![0usize; needle.len()];
|
||
let mut k = 0usize;
|
||
for (i, &b) in needle.iter().enumerate().skip(1) {
|
||
while k > 0 && needle.get(k) != Some(&b) {
|
||
k = table.get(k.saturating_sub(1)).copied().unwrap_or(0);
|
||
}
|
||
if needle.get(k) == Some(&b) {
|
||
k = k.saturating_add(1);
|
||
}
|
||
if let Some(slot) = table.get_mut(i) {
|
||
*slot = k;
|
||
}
|
||
}
|
||
table
|
||
}
|
||
|
||
/// Calls `found` with the start of every occurrence of `needle` in `hay`, overlapping ones included.
|
||
fn for_each_match(hay: &[u8], needle: &[u8], mut found: impl FnMut(usize)) {
|
||
let len = needle.len();
|
||
if len == 0 || len > hay.len() {
|
||
return;
|
||
}
|
||
let table = failure_table(needle);
|
||
let mut k = 0usize;
|
||
for (i, &b) in hay.iter().enumerate() {
|
||
while k > 0 && needle.get(k) != Some(&b) {
|
||
k = table.get(k.saturating_sub(1)).copied().unwrap_or(0);
|
||
}
|
||
if needle.get(k) == Some(&b) {
|
||
k = k.saturating_add(1);
|
||
}
|
||
if k == len {
|
||
found(i.saturating_add(1).saturating_sub(len));
|
||
k = table.get(len.saturating_sub(1)).copied().unwrap_or(0);
|
||
}
|
||
}
|
||
}
|
||
|
||
impl Redactor {
|
||
/// An empty redactor.
|
||
pub fn new() -> Self {
|
||
Self::default()
|
||
}
|
||
|
||
/// Adds a secret proper (a password, a token) in each of its written forms.
|
||
///
|
||
/// A form shorter than [`MIN_SECRET_LEN`] once normalised makes every excerpt withheld.
|
||
pub fn add(&mut self, secret: &str) {
|
||
self.add_forms(secret, true);
|
||
}
|
||
|
||
/// Adds personal data or an address (a user name, an account name, the session address) in each of its
|
||
/// written forms. A form shorter than [`MIN_SECRET_LEN`] is not looked for.
|
||
pub fn add_personal(&mut self, text: &str) {
|
||
self.add_forms(text, false);
|
||
}
|
||
|
||
fn add_forms(&mut self, text: &str, strong: bool) {
|
||
if text.is_empty() {
|
||
return;
|
||
}
|
||
let encoded = Secret::new(encode_component(text));
|
||
let form_encoded = Secret::new(encoded.expose().replace("%20", "+"));
|
||
for form in [text, encoded.expose(), form_encoded.expose()] {
|
||
self.push(form, strong);
|
||
}
|
||
}
|
||
|
||
fn push(&mut self, form: &str, strong: bool) {
|
||
let normalised = Secret::new(normalise(form, usize::MAX).0);
|
||
let needle = Secret::new(normalised.expose().to_ascii_lowercase());
|
||
if needle.expose().len() < MIN_SECRET_LEN {
|
||
if strong {
|
||
self.withhold = true;
|
||
}
|
||
return;
|
||
}
|
||
if !self.needles.iter().any(|known| known.expose() == needle.expose()) {
|
||
self.needles.push(needle);
|
||
}
|
||
}
|
||
|
||
/// How many written forms are looked for.
|
||
pub fn len(&self) -> usize {
|
||
self.needles.len()
|
||
}
|
||
|
||
/// Whether nothing is looked for.
|
||
pub fn is_empty(&self) -> bool {
|
||
self.needles.is_empty()
|
||
}
|
||
|
||
/// Whether `text` holds a known secret (or excerpts are withheld altogether).
|
||
pub fn mentions_secret(&self, text: &str) -> bool {
|
||
self.withhold || self.excerpt(text).as_str() != normalise(text, usize::MAX).0
|
||
}
|
||
|
||
/// Turns a server's text into an excerpt fit for an error message.
|
||
pub fn excerpt(&self, text: &str) -> Excerpt {
|
||
if self.withhold {
|
||
return Excerpt(WITHHELD.to_owned());
|
||
}
|
||
let longest = self.needles.iter().map(|needle| needle.expose().len()).max().unwrap_or(0);
|
||
let (normalised, cut_short) = normalise(text, SCAN_WINDOW.saturating_add(longest));
|
||
let normalised = Secret::new(normalised);
|
||
let shown = normalised.expose();
|
||
let window_end = floor_boundary(shown, SCAN_WINDOW);
|
||
let folded = Secret::new(shown.to_ascii_lowercase());
|
||
// ends[i]: the furthest end of a secret starting at octet i.
|
||
let mut ends = vec![0usize; window_end];
|
||
for needle in &self.needles {
|
||
let needle_len = needle.expose().len();
|
||
for_each_match(folded.expose().as_bytes(), needle.expose().as_bytes(), |start| {
|
||
if let Some(slot) = ends.get_mut(start) {
|
||
*slot = (*slot).max(start.saturating_add(needle_len));
|
||
}
|
||
});
|
||
}
|
||
let mut out = String::new();
|
||
let mut count = 0usize;
|
||
let mut covered_until = 0usize;
|
||
let mut in_mark = false;
|
||
let mut truncated = cut_short || window_end < shown.len();
|
||
for (index, c) in shown.get(..window_end).unwrap_or("").char_indices() {
|
||
for end in ends.iter().take(index.saturating_add(c.len_utf8())).skip(index) {
|
||
covered_until = covered_until.max(*end);
|
||
}
|
||
if index < covered_until {
|
||
if !in_mark {
|
||
if count.saturating_add(MARK_CHARS) > EXCERPT_MAX_CHARS {
|
||
truncated = true;
|
||
break;
|
||
}
|
||
out.push_str(MARK);
|
||
count = count.saturating_add(MARK_CHARS);
|
||
in_mark = true;
|
||
}
|
||
continue;
|
||
}
|
||
in_mark = false;
|
||
if count >= EXCERPT_MAX_CHARS {
|
||
truncated = true;
|
||
break;
|
||
}
|
||
out.push(c);
|
||
count = count.saturating_add(1);
|
||
}
|
||
if truncated {
|
||
let kept = out.trim_end().len();
|
||
out.truncate(kept);
|
||
out.push('…');
|
||
}
|
||
Excerpt(out)
|
||
}
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests;
|