hecks 3.10.0 → 3.12.0

data/rust/host/src/platform_signin/strict_json.rs

@@ -0,0 +1,351 @@
+//! A JSON reader that accepts only what two parsers could not disagree about.
+//!
+//! The standard parsers keep the last of a repeated key and accept deep nesting. A token whose
+//! header or claims repeat a key could be read one way here and another way by the issuer, so this
+//! reader refuses it. It also keeps numbers apart from each other (an integer is not a float)
+//! because
+//! the time claims must be integers.
+
+use std::collections::HashMap;
+
+/// A parsed JSON value, reduced to the shapes a token check needs to tell apart.
+#[derive(Debug, Clone, PartialEq)]
+pub enum Json {
+    Null,
+    Bool(bool),
+    /// An integer; a digit string beyond the `i128` range saturates, which keeps every comparison
+    /// against a time window the same as an unbounded integer would give.
+    Int(i128),
+    /// Any number that is not an integer literal (a fraction or an exponent).
+    Number,
+    Str(String),
+    Array(Vec<Json>),
+    Object(JsonObject),
+}
+
+/// A JSON object with unique keys.
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct JsonObject(HashMap<String, Json>);
+
+impl JsonObject {
+    /// Finds a member by name.
+    pub fn get(&self, name: &str) -> Option<&Json> {
+        self.0.get(name)
+    }
+
+    /// Finds a member that is a string.
+    pub fn get_str(&self, name: &str) -> Option<&str> {
+        match self.get(name) {
+            Some(Json::Str(text)) => Some(text),
+            _ => None,
+        }
+    }
+
+    /// Tells whether the member exists and is not JSON `null`.
+    pub fn is_present(&self, name: &str) -> bool {
+        !matches!(self.get(name), None | Some(Json::Null))
+    }
+
+    /// Lists the member names, in no particular order.
+    pub fn keys(&self) -> impl Iterator<Item = &String> {
+        self.0.keys()
+    }
+}
+
+/// The deepest nesting accepted, counting the outer object as depth 1.
+pub const MAX_DEPTH: usize = 8;
+
+/// Parses `bytes` as one JSON object and nothing else.
+///
+/// Returns `None` for invalid UTF-8, invalid JSON, trailing text, a value that is not an object,
+/// an object that repeats a key at any depth, and nesting deeper than [`MAX_DEPTH`].
+pub fn parse_object(bytes: &[u8]) -> Option<JsonObject> {
+    let text = std::str::from_utf8(bytes).ok()?;
+    let mut parser = Parser {
+        bytes: text.as_bytes(),
+        at: 0,
+    };
+    parser.skip_whitespace();
+    let object = parser.object(0)?;
+    parser.skip_whitespace();
+    (parser.at == parser.bytes.len()).then_some(object)
+}
+
+/// A recursive-descent reader over validated UTF-8; every method returns `None` at the first fault.
+struct Parser<'a> {
+    bytes: &'a [u8],
+    at: usize,
+}
+
+impl Parser<'_> {
+    fn peek(&self) -> Option<u8> {
+        self.bytes.get(self.at).copied()
+    }
+
+    fn skip_whitespace(&mut self) {
+        while matches!(self.peek(), Some(b' ' | b'\t' | b'\n' | b'\r')) {
+            self.at += 1;
+        }
+    }
+
+    fn expect(&mut self, byte: u8) -> Option<()> {
+        (self.peek() == Some(byte)).then(|| self.at += 1)
+    }
+
+    fn value(&mut self, depth: usize) -> Option<Json> {
+        match self.peek()? {
+            b'{' => self.object(depth).map(Json::Object),
+            b'[' => self.array(depth),
+            b'"' => self.string().map(Json::Str),
+            b't' => self.literal(b"true", Json::Bool(true)),
+            b'f' => self.literal(b"false", Json::Bool(false)),
+            b'n' => self.literal(b"null", Json::Null),
+            b'-' | b'0'..=b'9' => self.number(),
+            _ => None,
+        }
+    }
+
+    fn literal(&mut self, word: &[u8], value: Json) -> Option<Json> {
+        let end = self.at + word.len();
+        (self.bytes.get(self.at..end)? == word).then(|| {
+            self.at = end;
+            value
+        })
+    }
+
+    fn object(&mut self, depth: usize) -> Option<JsonObject> {
+        let depth = depth + 1;
+        if depth > MAX_DEPTH {
+            return None;
+        }
+        self.expect(b'{')?;
+        let mut members = HashMap::new();
+        self.skip_whitespace();
+        if self.peek() == Some(b'}') {
+            self.at += 1;
+            return Some(JsonObject(members));
+        }
+        loop {
+            self.skip_whitespace();
+            let key = self.string()?;
+            self.skip_whitespace();
+            self.expect(b':')?;
+            self.skip_whitespace();
+            let value = self.value(depth)?;
+            if members.insert(key, value).is_some() {
+                return None;
+            }
+            self.skip_whitespace();
+            match self.peek()? {
+                b',' => self.at += 1,
+                b'}' => {
+                    self.at += 1;
+                    return Some(JsonObject(members));
+                }
+                _ => return None,
+            }
+        }
+    }
+
+    fn array(&mut self, depth: usize) -> Option<Json> {
+        let depth = depth + 1;
+        if depth > MAX_DEPTH {
+            return None;
+        }
+        self.expect(b'[')?;
+        let mut items = Vec::new();
+        self.skip_whitespace();
+        if self.peek() == Some(b']') {
+            self.at += 1;
+            return Some(Json::Array(items));
+        }
+        loop {
+            self.skip_whitespace();
+            items.push(self.value(depth)?);
+            self.skip_whitespace();
+            match self.peek()? {
+                b',' => self.at += 1,
+                b']' => {
+                    self.at += 1;
+                    return Some(Json::Array(items));
+                }
+                _ => return None,
+            }
+        }
+    }
+
+    fn string(&mut self) -> Option<String> {
+        self.expect(b'"')?;
+        let mut out: Vec<u8> = Vec::new();
+        loop {
+            let byte = self.peek()?;
+            self.at += 1;
+            match byte {
+                b'"' => return String::from_utf8(out).ok(),
+                b'\\' => self.escape(&mut out)?,
+                0x00..=0x1f => return None,
+                other => out.push(other),
+            }
+        }
+    }
+
+    fn escape(&mut self, out: &mut Vec<u8>) -> Option<()> {
+        let byte = self.peek()?;
+        self.at += 1;
+        let simple = match byte {
+            b'"' => b'"',
+            b'\\' => b'\\',
+            b'/' => b'/',
+            b'b' => 0x08,
+            b'f' => 0x0c,
+            b'n' => b'\n',
+            b'r' => b'\r',
+            b't' => b'\t',
+            b'u' => return self.unicode_escape(out),
+            _ => return None,
+        };
+        out.push(simple);
+        Some(())
+    }
+
+    fn unicode_escape(&mut self, out: &mut Vec<u8>) -> Option<()> {
+        let first = self.hex4()?;
+        let code = match first {
+            0xD800..=0xDBFF => {
+                self.expect(b'\\')?;
+                self.expect(b'u')?;
+                let second = self.hex4()?;
+                if !(0xDC00..=0xDFFF).contains(&second) {
+                    return None;
+                }
+                0x10000 + ((first - 0xD800) << 10) + (second - 0xDC00)
+            }
+            0xDC00..=0xDFFF => return None,
+            plain => plain,
+        };
+        let mut buffer = [0u8; 4];
+        out.extend_from_slice(char::from_u32(code)?.encode_utf8(&mut buffer).as_bytes());
+        Some(())
+    }
+
+    fn hex4(&mut self) -> Option<u32> {
+        let digits = self.bytes.get(self.at..self.at + 4)?;
+        let text = std::str::from_utf8(digits).ok()?;
+        if !text.bytes().all(|b| b.is_ascii_hexdigit()) {
+            return None;
+        }
+        self.at += 4;
+        u32::from_str_radix(text, 16).ok()
+    }
+
+    fn digits(&mut self) -> Option<usize> {
+        let start = self.at;
+        while matches!(self.peek(), Some(b'0'..=b'9')) {
+            self.at += 1;
+        }
+        (self.at > start).then_some(self.at - start)
+    }
+
+    fn number(&mut self) -> Option<Json> {
+        let negative = self.peek() == Some(b'-');
+        if negative {
+            self.at += 1;
+        }
+        let integer_start = self.at;
+        if self.peek() == Some(b'0') {
+            self.at += 1;
+        } else {
+            self.digits()?;
+        }
+        let integer_end = self.at;
+        let mut integral = true;
+        if self.peek() == Some(b'.') {
+            self.at += 1;
+            self.digits()?;
+            integral = false;
+        }
+        if matches!(self.peek(), Some(b'e' | b'E')) {
+            self.at += 1;
+            if matches!(self.peek(), Some(b'+' | b'-')) {
+                self.at += 1;
+            }
+            self.digits()?;
+            integral = false;
+        }
+        if !integral {
+            return Some(Json::Number);
+        }
+        let text = std::str::from_utf8(&self.bytes[integer_start..integer_end]).ok()?;
+        Some(Json::Int(integer_from(text, negative)))
+    }
+}
+
+/// Reads an integer literal's digits, saturating at the `i128` limits instead of failing.
+fn integer_from(digits: &str, negative: bool) -> i128 {
+    match digits.parse::<i128>() {
+        Ok(value) if negative => -value,
+        Ok(value) => value,
+        Err(_) if negative => i128::MIN,
+        Err(_) => i128::MAX,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn parse(text: &str) -> Option<JsonObject> {
+        parse_object(text.as_bytes())
+    }
+
+    #[test]
+    fn an_object_parses_and_its_members_are_readable() {
+        let object = parse(r#"{"a":"x","b":7,"c":true,"d":null}"#).expect("object");
+        assert_eq!(object.get_str("a"), Some("x"));
+        assert_eq!(object.get("b"), Some(&Json::Int(7)));
+        assert_eq!(object.get("c"), Some(&Json::Bool(true)));
+        assert!(!object.is_present("d"));
+        assert!(!object.is_present("missing"));
+    }
+
+    #[test]
+    fn a_repeated_key_is_refused_at_the_top_and_when_nested() {
+        assert!(parse(r#"{"a":1,"a":2}"#).is_none());
+        assert!(parse(r#"{"a":{"b":1,"b":1}}"#).is_none());
+        assert!(parse(r#"{"a":[{"b":1,"b":1}]}"#).is_none());
+    }
+
+    #[test]
+    fn only_an_object_is_accepted() {
+        for text in [
+            "[]", "\"s\"", "1", "true", "null", "", "   ", "{", "{}x", "{} {}",
+        ] {
+            assert!(parse(text).is_none(), "{text:?} must be refused");
+        }
+        assert!(parse("{}").is_some());
+        assert!(parse(" {} ").is_some());
+    }
+
+    #[test]
+    fn invalid_utf8_is_refused() {
+        assert!(parse_object(b"{\"a\":\"\xff\"}").is_none());
+    }
+
+    #[test]
+    fn integers_and_other_numbers_are_told_apart() {
+        let object = parse(r#"{"i":-5,"f":1.5,"e":1e2,"z":1.0,"big":99999999999999999999999999999999999999999999}"#).expect("object");
+        assert_eq!(object.get("i"), Some(&Json::Int(-5)));
+        assert_eq!(object.get("f"), Some(&Json::Number));
+        assert_eq!(object.get("e"), Some(&Json::Number));
+        assert_eq!(object.get("z"), Some(&Json::Number));
+        assert_eq!(object.get("big"), Some(&Json::Int(i128::MAX)));
+    }
+
+    #[test]
+    fn nesting_is_capped_at_eight_levels() {
+        let ok = format!(r#"{{"a":{}{}}}"#, "[".repeat(7), "]".repeat(7));
+        assert!(parse(&ok).is_some(), "depth 8 is allowed");
+        let deep = format!(r#"{{"a":{}{}}}"#, "[".repeat(8), "]".repeat(8));
+        assert!(parse(&deep).is_none(), "depth 9 is refused");
+    }
+}

data/rust/host/src/platform_signin/test_support.rs

@@ -0,0 +1,235 @@
+//! Shared scaffolding for this module's tests: throwaway keys, a signer, and a scenario builder.
+//!
+//! The seeds are the public throwaway seeds of the known-answer vectors; they are used for nothing
+//! else and protect nothing. Tokens are signed with `jsonwebtoken`'s own signer so the tests do not
+//! need a second crypto dependency.
+
+use std::collections::HashMap;
+
+use jsonwebtoken::{Algorithm, EncodingKey};
+use serde_json::{json, Map, Value};
+
+use super::config::PlatformSigninConfig;
+use super::jti::JtiStore;
+use super::jwks::{thumbprint, KeySource, VerifyingKey};
+use super::jws::encode_base64url;
+use super::strict_json::{Json, JsonObject};
+use super::verify::{Refusal, SigninCookie, SigninRequest, VerifiedClaims, Verifier};
+
+pub const NOW: i64 = 1_800_000_000;
+pub const ISSUER: &str = "https://issuer.example";
+pub const SITE: &str = "site-a";
+pub const ENVIRONMENT: &str = "production";
+pub const EMAIL: &str = "person@example.test";
+pub const NONCE: &str = "Nn0nceNn0nceNn0nceAA";
+pub const STATE: &str = "StateStateState0123456789";
+
+pub const X_A: &str = "BrQXFhWGK4Fmi8rRsnn1KzomYanZaWCsFWaS0Dgv62k";
+pub const KID_A: &str = "SwpkMw_CknhH156gpWgzPJOQNEGnS25LhD1OqeNsQko";
+pub const X_B: &str = "y4eb9h3HL-Ojhu6bp87lvE1Nl6b8YjIqM_AGXTRMeB0";
+
+/// A throwaway Ed25519 key pair: its seed and its public `x`.
+#[derive(Clone, Copy)]
+pub struct TestKey {
+    seed: &'static [u8; 32],
+    pub x: &'static str,
+}
+
+pub const KEY_A: TestKey = TestKey {
+    seed: b"TEST-ONLY-KNOWN-ANSWER-SEED-0001",
+    x: X_A,
+};
+pub const KEY_B: TestKey = TestKey {
+    seed: b"TEST-ONLY-KNOWN-ANSWER-SEED-0002",
+    x: X_B,
+};
+
+impl TestKey {
+    /// Returns the key's thumbprint, which is its `kid`.
+    pub fn kid(&self) -> String {
+        thumbprint(self.x)
+    }
+
+    /// Returns the public half as a verifying key.
+    pub fn verifying(&self) -> VerifyingKey {
+        VerifyingKey::from_x(self.x).expect("a valid public key")
+    }
+
+    /// Signs `input` as EdDSA and returns the unpadded base64url signature.
+    pub fn sign(&self, input: &str) -> String {
+        let mut der = vec![
+            0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22,
+            0x04, 0x20,
+        ];
+        der.extend_from_slice(self.seed);
+        let key = EncodingKey::from_ed_der(&der);
+        jsonwebtoken::crypto::sign(input.as_bytes(), &key, Algorithm::EdDSA).expect("signs")
+    }
+}
+
+/// Builds `header.claims.signature` from raw JSON texts, signed by `key`.
+pub fn assemble(header_text: &str, claims_text: &str, key: &TestKey) -> String {
+    let input = format!(
+        "{}.{}",
+        encode_base64url(header_text.as_bytes()),
+        encode_base64url(claims_text.as_bytes())
+    );
+    format!("{input}.{}", key.sign(&input))
+}
+
+/// A key source that holds a fixed set of keys, by computed thumbprint.
+pub struct StaticKeys(pub HashMap<String, VerifyingKey>);
+
+impl KeySource for StaticKeys {
+    fn key_for(&self, kid: &str, _now: i64) -> Option<VerifyingKey> {
+        self.0.get(kid).cloned()
+    }
+}
+
+/// Builds a key source holding exactly `keys`.
+pub fn static_keys(keys: &[&TestKey]) -> StaticKeys {
+    StaticKeys(keys.iter().map(|k| (k.kid(), k.verifying())).collect())
+}
+
+/// Returns the pinned configuration the vectors use.
+pub fn config() -> PlatformSigninConfig {
+    PlatformSigninConfig::new(
+        ISSUER,
+        "https://issuer.example/.well-known/jwks.json",
+        SITE,
+        ENVIRONMENT,
+    )
+}
+
+/// Builds a verifier that trusts exactly `keys`, with an empty single-use record.
+pub fn verifier_for(keys: &[&TestKey]) -> Verifier<StaticKeys> {
+    Verifier::new(config(), static_keys(keys), JtiStore::new())
+}
+
+/// Returns the sign-in cookie that matches a good scenario.
+pub fn good_cookie() -> SigninCookie {
+    SigninCookie {
+        nonce: NONCE.into(),
+        state: STATE.into(),
+    }
+}
+
+/// Turns a verified or raw claim object into a `serde_json::Value`, for comparisons.
+pub fn to_value(json: &Json) -> Value {
+    match json {
+        Json::Null => Value::Null,
+        Json::Bool(b) => Value::Bool(*b),
+        Json::Int(i) => Value::from(i64::try_from(*i).unwrap_or(i64::MAX)),
+        Json::Number => Value::from(0.5),
+        Json::Str(s) => Value::String(s.clone()),
+        Json::Array(items) => Value::Array(items.iter().map(to_value).collect()),
+        Json::Object(object) => object_to_value(object),
+    }
+}
+
+/// Turns a parsed object into a `serde_json::Value`.
+pub fn object_to_value(object: &JsonObject) -> Value {
+    Value::Object(
+        object
+            .keys()
+            .map(|k| (k.clone(), to_value(object.get(k).expect("member"))))
+            .collect(),
+    )
+}
+
+/// One sign-in attempt, built from a good one by mutating the pieces a test wants to break.
+pub struct Scenario {
+    pub header: Map<String, Value>,
+    pub claims: Map<String, Value>,
+    pub signer: TestKey,
+    pub state: Option<String>,
+    pub cookie: Option<SigninCookie>,
+    pub flip_signature: bool,
+    pub replace_token: Option<String>,
+    pub spend_first: bool,
+    pub now: i64,
+}
+
+impl Scenario {
+    /// Builds a scenario that a verifier accepts.
+    pub fn good() -> Self {
+        let claims = json!({
+            "iss": ISSUER, "aud": SITE, "env": ENVIRONMENT, "sub": EMAIL,
+            "idp_iss": "https://idp.example", "idp_sub": "idp-subject-0001",
+            "email": EMAIL, "email_verified": true, "roles": ["Admin"], "nonce": NONCE,
+            "iat": NOW, "nbf": NOW, "exp": NOW + 60, "jti": "jti-scenario-0000000000"
+        });
+        let header = json!({"alg": "EdDSA", "typ": "JWT", "kid": KEY_A.kid()});
+        Self {
+            header: header.as_object().cloned().unwrap(),
+            claims: claims.as_object().cloned().unwrap(),
+            signer: KEY_A,
+            state: Some(STATE.into()),
+            cookie: Some(good_cookie()),
+            flip_signature: false,
+            replace_token: None,
+            spend_first: false,
+            now: NOW,
+        }
+    }
+
+    /// Builds the token text, signed over the (possibly mutated) header and claims.
+    pub fn token(&self) -> String {
+        if let Some(text) = &self.replace_token {
+            return text.clone();
+        }
+        let header = Value::Object(self.header.clone()).to_string();
+        let claims = Value::Object(self.claims.clone()).to_string();
+        let token = assemble(&header, &claims, &self.signer);
+        if self.flip_signature {
+            flip_last_signature_bit(&token)
+        } else {
+            token
+        }
+    }
+
+    /// Runs the scenario through `verifier`, spending the jti first when asked.
+    pub fn run(&self, verifier: &Verifier<StaticKeys>) -> Result<VerifiedClaims, Refusal> {
+        if self.spend_first {
+            let jti = self
+                .claims
+                .get("jti")
+                .and_then(Value::as_str)
+                .expect("a jti to spend");
+            assert!(verifier.jti_store().claim(jti, self.now + 90, self.now));
+        }
+        let token = self.token();
+        let request = SigninRequest {
+            token: Some(&token),
+            state: self.state.as_deref(),
+            cookie: self.cookie.as_ref(),
+        };
+        verifier.verify(&request, self.now)
+    }
+}
+
+/// Changes the first bit of the signature's first byte, keeping the segment canonical.
+pub fn flip_last_signature_bit(token: &str) -> String {
+    let (input, signature) = token.rsplit_once('.').expect("three segments");
+    let mut bytes = super::jws::decode_base64url(signature).expect("canonical signature");
+    bytes[0] ^= 1;
+    format!("{input}.{}", encode_base64url(&bytes))
+}
+
+/// A key-set fetcher backed by a closure, for cache tests.
+pub struct FnFetcher(pub Box<dyn Fn() -> Result<String, super::jwks::FetchFailed> + Send + Sync>);
+
+impl super::jwks::JwksFetcher for FnFetcher {
+    fn fetch(&self) -> Result<String, super::jwks::FetchFailed> {
+        (self.0)()
+    }
+}
+
+/// A key set document listing `keys`.
+pub fn jwks_document(keys: &[&TestKey]) -> String {
+    let entries: Vec<String> = keys
+        .iter()
+        .map(|k| format!(r#"{{"kty":"OKP","crv":"Ed25519","x":"{}"}}"#, k.x))
+        .collect();
+    format!(r#"{{"keys":[{}]}}"#, entries.join(","))
+}

data/rust/host/src/platform_signin/ttl_tests.rs

@@ -0,0 +1,94 @@
+//! The key set cache honours how long the issuer says its answer may be kept, within bounds.
+
+use std::sync::atomic::{AtomicI64, AtomicUsize, Ordering};
+use std::sync::Arc;
+
+use super::jwks::{FetchFailed, JwksCache, JwksFetcher, KeySource, MAX_TTL_SECONDS};
+use super::test_support::{jwks_document, KEY_A};
+
+struct Hinted {
+    fetches: Arc<AtomicUsize>,
+    hint: Arc<AtomicI64>,
+}
+
+impl JwksFetcher for Hinted {
+    fn fetch(&self) -> Result<String, FetchFailed> {
+        self.fetches.fetch_add(1, Ordering::SeqCst);
+        Ok(jwks_document(&[&KEY_A]))
+    }
+
+    fn ttl_hint(&self) -> Option<i64> {
+        let hint = self.hint.load(Ordering::SeqCst);
+        (hint >= 0).then_some(hint)
+    }
+}
+
+const START: i64 = 1_000;
+
+fn cache(hint: i64) -> (JwksCache<Hinted>, Arc<AtomicUsize>, Arc<AtomicI64>) {
+    let fetches = Arc::new(AtomicUsize::new(0));
+    let hint = Arc::new(AtomicI64::new(hint));
+    let fetcher = Hinted {
+        fetches: fetches.clone(),
+        hint: hint.clone(),
+    };
+    (JwksCache::new(fetcher), fetches, hint)
+}
+
+/// Asks for the known key at `START + offset` and returns how many fetches have happened.
+fn ask(cache: &JwksCache<Hinted>, fetches: &AtomicUsize, offset: i64) -> usize {
+    assert!(cache.key_for(&KEY_A.kid(), START + offset).is_some());
+    fetches.load(Ordering::SeqCst)
+}
+
+#[test]
+fn without_a_hint_the_default_time_to_live_applies() {
+    let (cache, fetches, _) = cache(-1);
+    assert_eq!(ask(&cache, &fetches, 0), 1);
+    assert_eq!(ask(&cache, &fetches, 299), 1);
+    assert_eq!(ask(&cache, &fetches, 300), 2);
+}
+
+#[test]
+fn a_shorter_hint_makes_the_keys_stale_sooner() {
+    let (cache, fetches, _) = cache(120);
+    assert_eq!(ask(&cache, &fetches, 0), 1);
+    assert_eq!(ask(&cache, &fetches, 119), 1);
+    assert_eq!(ask(&cache, &fetches, 120), 2);
+}
+
+#[test]
+fn a_longer_hint_keeps_the_keys_longer() {
+    let (cache, fetches, _) = cache(900);
+    assert_eq!(ask(&cache, &fetches, 0), 1);
+    assert_eq!(ask(&cache, &fetches, 899), 1);
+    assert_eq!(ask(&cache, &fetches, 900), 2);
+}
+
+#[test]
+fn a_huge_hint_is_capped() {
+    let (cache, fetches, _) = cache(10_000_000);
+    assert_eq!(ask(&cache, &fetches, 0), 1);
+    assert_eq!(ask(&cache, &fetches, MAX_TTL_SECONDS - 1), 1);
+    assert_eq!(ask(&cache, &fetches, MAX_TTL_SECONDS), 2);
+}
+
+#[test]
+fn a_tiny_hint_cannot_turn_the_cache_into_a_fetch_amplifier() {
+    for hint in [0, 1, 29] {
+        let (cache, fetches, _) = cache(hint);
+        assert_eq!(ask(&cache, &fetches, 0), 1, "hint {hint}");
+        assert_eq!(ask(&cache, &fetches, 29), 1, "hint {hint}");
+        assert_eq!(ask(&cache, &fetches, 30), 2, "hint {hint}");
+    }
+}
+
+#[test]
+fn the_next_fetch_without_a_hint_returns_to_the_default() {
+    let (cache, fetches, hint) = cache(60);
+    assert_eq!(ask(&cache, &fetches, 0), 1);
+    hint.store(-1, Ordering::SeqCst);
+    assert_eq!(ask(&cache, &fetches, 60), 2);
+    assert_eq!(ask(&cache, &fetches, 60 + 299), 2);
+    assert_eq!(ask(&cache, &fetches, 60 + 300), 3);
+}