Trusted time: judge a fetched attestation at its integrated time 028545dfa7a4

//! in (the transparency log's integrated time, §14.8, else a host's

//! acceptance).

    /// The witnesses the host asks to cosign its checkpoints: each one's

    /// name in cosignatures and its identity's bytes (key 7, only when it

    /// has any), which a client pins (spec §14.8, *Integrated time*).

    pub witnesses: Vec<(String, Vec<u8>)>,

/// A checkpoint witnesses cosigned that includes a logged entry (spec

/// §14.8, *Integrated time*): the cosigned note, and the entry's inclusion

/// proof against it.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Integration {

    pub note: String,

    pub proof: Vec<[u8; 32]>,

}

    /// The cosigned checkpoints that first included `logged`'s entry (key

    /// 7, only when there are any): what its integrated time is read from.

    pub integration: Vec<Integration>,

                                            proof_value(&l.proof),

                                if !r.integration.is_empty() {

                                    m.insert(

                                        7,

                                        Value::Array(

                                            r.integration

                                                .iter()

                                                .map(|i| {

                                                    Value::Array(vec![

                                                        Value::Text(i.note.clone()),

                                                        proof_value(&i.proof),

                                                    ])

                                                })

                                                .collect(),

                                        ),

                                    );

                                }

        if let Value::Map(m) = &mut v {

            if let Some(log) = &resp.log {

                m.insert(6, Value::Text(log.clone()));

            }

            if !resp.witnesses.is_empty() {

                m.insert(

                    7,

                    Value::Array(

                        resp.witnesses

                            .iter()

                            .map(|(name, id)| {

                                Value::Array(vec![

                                    Value::Text(name.clone()),

                                    Value::Bytes(id.clone()),

                                ])

                            })

                            .collect(),

                    ),

                );

            }

                            proof: proof_from(&a[2])?,

                integration: match rm.get(&7) {

                    Some(l) => {

                        let mut out = Vec::new();

                        for i in o::array(l, "integration")? {

                            let a = o::array(i, "integration")?;

                            if a.len() != 2 {

                                return Err(schema("integration: expected [note, proof]"));

                            }

                            out.push(Integration {

                                note: o::text(&a[0], "note")?.to_owned(),

                                proof: proof_from(&a[1])?,

                            });

                        }

                        out

                    }

                    None => Vec::new(),

                },

        let mut witnesses = Vec::new();

        if let Some(w) = m.get(&7) {

            for x in o::array(w, "witnesses")? {

                let a = o::array(x, "witness")?;

                if a.len() != 2 {

                    return Err(schema("witness: expected [name, identity]"));

                }

                witnesses.push((

                    o::text(&a[0], "witness name")?.to_owned(),

                    o::bytes(&a[1], "witness identity")?.to_vec(),

                ));

            }

        }

                witnesses,

    /// A proof's hashes, from the leaf upwards (spec §14.8).

    fn proof_value(proof: &[[u8; 32]]) -> Value {

        Value::Array(proof.iter().map(|h| Value::Bytes(h.to_vec())).collect())

    }

    fn proof_from(v: &Value) -> Result<Vec<[u8; 32]>> {

        let mut proof = Vec::new();

        for h in o::array(v, "proof")? {

            proof.push(

                o::bytes(h, "proof hash")?

                    .try_into()

                    .map_err(|_| schema("proof hash: expected 32 bytes"))?,

            );

        }

        Ok(proof)

    }

                integration: vec![],

                integration: vec![],

            witnesses: vec![],

        // Without integrated times (spec §14.8) nothing is added: an old

        // peer's answer, and what it reads.

        let old = wire::encode_refs([3; 16], &resp);

        let back = wire::decode_refs(&old).unwrap().1;

        assert!(back.witnesses.is_empty() && back.refs.iter().all(|r| r.integration.is_empty()));

        resp.refs[1].integration = vec![Integration {

            note: "hub.example/log\n42\nroot\n\n- sig\n".into(),

            proof: vec![[7; 32]],

        }];

        resp.witnesses = vec![("w.example".into(), vec![4, 5, 6])];

        let new = wire::encode_refs([3; 16], &resp);

        let (id_back, back) = wire::decode_refs(&new).unwrap();

        assert_eq!(back.refs[1].integration, resp.refs[1].integration);

        assert_eq!(back.witnesses, resp.witnesses);

        // The new keys are 7s an old reader never asks for.

        let crate::cbor::Value::Map(m) = crate::cbor::decode(&new).unwrap() else {

            panic!()

        };

        assert!(m.contains_key(&7));

                integration: vec![],

            witnesses: vec![],

    /// A fetched bookmark's attestation by a signer the policy does not

    /// list itself: a delegate or a short-lived key, whose authority

    /// depends on when it signed (spec §14.5, §14.8). Checked at the

    /// attestation's integrated time when the host's log gives one; else

    /// as before, at the host's acceptance for a certified signer, when it

    /// countersigned one, or at the attestation's own time, and said so

    /// when the host keeps a log. Failing at the integrated time but not

    /// as before is a note while logs are new; a large gap between the

    /// claimed and the integrated time is a note.

    #[allow(clippy::too_many_arguments)]

    pub(crate) fn authorize_in_time(

        &self,

        p: &crate::policy::Policy,

        remote_name: &str,

        r: &crate::protocol::RemoteRef,

        sa: &SignedAttest,

        signer: &KeyId,

        log: &super::transparency::LogCheck,

        notes: &mut Vec<String>,

    ) -> Result<()> {

        use super::transparency::{gap_note, judge, Timed};

        let own = sa.attest.hlc.wall_ms;

        let at = self.certified_time(signer, sa, r.accepted.as_ref());

        let time = log.time_of(&r.name);

        let check = |t_delegate: u64, t_cert: u64| {

            self.delegate_authorized(p, signer, &r.name, t_delegate)

                || self.certified_authorized(p, signer, &r.name, Scope::REFS, t_cert)

        };

        let before = if at != own {

            "the host's acceptance"

        } else {

            "the time it claims"

        };

        let what = format!("{remote_name}/{}", r.name);

        match judge(time.as_ref().ok().map(|i| i.ms()), |t| check(t, t), || check(own, at)) {

            Timed::Refused => {

                return fail(format!(

                    "{what}: attested by {}, which the policy does not authorize for this bookmark; a policy owner can grant it with `oxy policy grant`",

                    signer.short(12)

                ))

            }

            Timed::Integrated => {}

            Timed::Disagrees => notes.push(format!(

                "{what}: {}'s authority had lapsed when witness {} first saw its attestation, though not at {before}; accepted while transparency logs are new",

                signer.short(12),

                time.as_ref().map(|i| i.witness.as_str()).unwrap_or("?")

            )),

            Timed::Fallback if log.kept => notes.push(format!(

                "{what}: {} checked at {before}, not at a witnessed time: {}",

                signer.short(12),

                time.as_ref().err().map(String::as_str).unwrap_or("none")

            )),

            Timed::Fallback => {}

        }

        if let Some(n) = time.ok().and_then(|i| gap_note(own, i)) {

            notes.push(format!("{what}'s attestation {n}"));

        }

        Ok(())

    }

        let log = self.check_log(

        let mut log_notes = log.notes.clone();

                if !p.authorizes(&signer, &r.name) {

                    self.authorize_in_time(p, remote_name, &r, sa, &signer, &log, &mut log_notes)?;

/// Trusted time (oxygenhub#240, spec §14.8): a fetched attestation by a

/// short-lived key is judged at its integrated time, the earliest time a

/// pinned witness cosigned a checkpoint holding it. A certificate valid

/// then but expired now passes; a witness this user does not trust gives

/// no time (the earlier rule, said so); a backdated attestation is noted;

/// an answer without the new fields is judged as before.

#[test]

fn a_fetched_attestation_is_judged_at_its_integrated_time() {

    use super::transparency::LogCheck;

    use crate::cert::{Certificate, SignedCertificate};

    use crate::identity::Scope;

    use crate::protocol::{Integration, Logged, RefsResponse, RemoteRef};

    use crate::tlog::{self, Checkpoint, Entry, Hash, Integrated, Note};

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let root = dir.path();

    let mut a = Repo::init(&root.join("a"))

        .unwrap()

        .with_home(root.join("home-a"));

    a.create_identity("Ada", "[email protected]", IdentityScope::User)

        .unwrap();

    write(&root.join("a"), "a.txt", b"a\n");

    a.commit("a", &[]).unwrap();

    a.policy_init().unwrap();

    let issuer_sk = SecretKey::generate();

    let issuer = issuer_sk.identity("hub", "[email protected]", 1);

    a.policy_grant_subject(

        "agent:claude@ada",

        issuer.clone(),

        Scope::CHANGES | Scope::REFS,

        None,

    )

    .unwrap();

    let p = a.current_policy().unwrap().unwrap().1.policy;

    // An agent key the issuer certified for ten minutes two hours ago.

    let now = Hlc::now().wall_ms;

    let t0 = now - 2 * 3_600_000;

    let agent_sk = SecretKey::generate();

    let agent = agent_sk.identity("claude", "[email protected]", t0);

    let cert = SignedCertificate::sign(

        Certificate {

            key: agent.clone(),

            issuer: issuer.hash(),

            subject: "agent:claude@ada".into(),

            claims: vec![],

            scope: Scope::CHANGES | Scope::REFS,

            not_before: t0,

            expires: t0 + 600_000,

            grant: None,

        },

        &issuer,

        &issuer_sk,

    );

    a.store().put_identity(&agent).unwrap();

    a.store().put_certificate(&cert).unwrap();

    let signer = agent.hash();

    let attested = |claimed: u64| {

        let attest = Attest {

            repo: a.id().unwrap(),

            hlc: Hlc {

                wall_ms: claimed,

                logical: 0,

            },

            body: AttestBody::Ref {

                name: "main".into(),

                old_state: ObjectRef([1; 32]),

                new_state: ObjectRef([2; 32]),

                serial: 1,

            },

        };

        let sig = agent_sk.sign(Domain::Attest, &signer, &attest.hash());

        SignedAttest {

            attest,

            sigs: vec![sig],

        }

    };

    // The hub's log: eight entries, the attestation's at 3, the latest

    // checkpoint of 8, and one of 4 that witnesses cosigned.

    let log_sk = SecretKey::generate();

    let log_key = log_sk.identity("hub.example", "[email protected]", 1);

    let origin = "hub.example/log";

    let hub = "https://hub.example";

    let url = "https://hub.example/ada/a";

    let w_sk = SecretKey::generate();

    let w = w_sk.identity("w", "[email protected]", 1);

    let stranger_sk = SecretKey::generate();

    let stranger = stranger_sk.identity("s", "[email protected]", 1);

    let sa = attested(t0 + 300_000);

    let entry_of = |i: u64| {

        let (kind, object) = if i == 3 {

            ("ref", sa.attest.hash())

        } else {

            ("seal", ObjectRef([i as u8; 32]))

        };

        Entry {

            kind: kind.into(),

            repo: sa.attest.repo,

            object,

            signers: vec![signer],

            received: t0 + 300_000,

        }

        .encode()

    };

    let mut stored: Vec<Hash> = Vec::new();

    for i in 0..8 {

        let add = tlog::stored_hashes_for_leaf(i, tlog::leaf_hash(&entry_of(i)), &stored).unwrap();

        stored.extend(add);

    }

    let note_of = |n: u64, cosigners: &[(&str, &Identity, &SecretKey, u64)]| {

        let mut note = Checkpoint {

            origin: origin.into(),

            size: n,

            root: tlog::tree_hash(n, &stored).unwrap(),

            extensions: vec![],

        }

        .sign(&log_key, &log_sk)

        .unwrap();

        for (name, id, sk, t) in cosigners {

            note.sigs

                .extend(tlog::cosign(&note.text, name, id, sk, *t).unwrap());

        }

        note.encode()

    };

    let latest = note_of(8, &[]);

    let witnessed_at = (t0 + 360_000) / 1000;

    let cosigned = note_of(

        4,

        &[

            ("w.example", &w, &w_sk, witnessed_at),

            ("s.example", &stranger, &stranger_sk, 1),

        ],

    );

    let answer = |integration: Vec<Integration>, witnesses: Vec<(String, Vec<u8>)>| RefsResponse {

        refs: vec![RemoteRef {

            name: "main".into(),

            state: ObjectRef([2; 32]),

            heads: vec![],

            attestation: Some(sa.clone()),

            last_serial: None,

            accepted: None,

            logged: Some(Logged {

                index: 3,

                entry: entry_of(3),

                proof: tlog::prove_inclusion(8, 3, &stored).unwrap(),

            }),

            integration,

        }],

        log: Some(latest.clone()),

        witnesses,

        ..RefsResponse::default()

    };

    let proof4 = tlog::prove_inclusion(4, 3, &stored).unwrap();

    let served = vec![Integration {

        note: cosigned.clone(),

        proof: proof4.clone(),

    }];

    let listed = vec![("w.example".to_string(), w.encode())];

    // This user saw the hub's log before (pinned, so nothing is fetched).

    a.remember_log(hub, &log_key, &Note::parse(&latest).unwrap())

        .unwrap();

    // The witness is pinned on first sight, silently; the stranger's

    // earlier cosignature counts for nothing.

    let resp = answer(served.clone(), listed.clone());

    let lc = a.check_log(url, None, &resp).unwrap();

    assert!(lc.notes.is_empty(), "{:?}", lc.notes);

    let t = lc.time_of("main").unwrap();

    assert_eq!((t.time, t.witness.as_str()), (witnessed_at, "w.example"));

    // The certificate expired an hour and fifty minutes ago, but covered

    // the integrated time: accepted, and nothing to say.

    assert!(cert.cert.expires < now);

    let mut notes = Vec::new();

    a.authorize_in_time(&p, "origin", &resp.refs[0], &sa, &signer, &lc, &mut notes)

        .unwrap();

    assert!(notes.is_empty(), "{notes:?}");

    // Only the stranger cosigned: no witnessed time, so the earlier rule

    // (the attestation's own time, inside the window), said so.

    let lonely = vec![Integration {

        note: note_of(4, &[("s.example", &stranger, &stranger_sk, 1)]),

        proof: proof4.clone(),

    }];

    let resp = answer(lonely, vec![]);

    let lc = a.check_log(url, None, &resp).unwrap();

    assert!(lc

        .time_of("main")

        .unwrap_err()

        .contains("no witness this user trusts"));

    let mut notes = Vec::new();

    a.authorize_in_time(&p, "origin", &resp.refs[0], &sa, &signer, &lc, &mut notes)

        .unwrap();

    assert!(

        notes.len() == 1 && notes[0].contains("not at a witnessed time"),

        "{notes:?}"

    );

    // A witness listed later under the pinned name with another key is

    // pinned with a note, as a new log key is.

    let resp = answer(

        served.clone(),

        vec![("w.example".into(), stranger.encode())],

    );

    let lc = a.check_log(url, None, &resp).unwrap();

    assert!(

        lc.notes.iter().any(|n| n.contains("another key")),

        "{:?}",

        lc.notes

    );

    assert!(

        lc.time_of("main").is_err(),

        "w's cosignature is by its old key"

    );

    a.check_log(url, None, &answer(served.clone(), listed.clone()))

        .unwrap();

    // An old peer's answer: no log, no witnesses, no integration. Judged

    // as before, silently.

    let mut old = answer(vec![], vec![]);

    old.log = None;

    old.refs[0].logged = None;

    let lc = a.check_log(url, None, &old).unwrap();

    assert!(!lc.kept && lc.notes.is_empty());

    let mut notes = Vec::new();

    a.authorize_in_time(&p, "origin", &old.refs[0], &sa, &signer, &lc, &mut notes)

        .unwrap();

    assert!(notes.is_empty(), "{notes:?}");

    // Judged at given integrated times.

    let at = |secs_after_t0: u64| {

        let mut times = std::collections::HashMap::new();

        times.insert(

            "main".to_string(),

            Ok(Integrated {

                time: (t0 + secs_after_t0 * 1000) / 1000,

                witness: "w.example".into(),

                size: 4,

            }),

        );

        LogCheck {

            kept: true,

            times,

            ..LogCheck::default()

        }

    };

    let judged = |sa: &SignedAttest, lc: &LogCheck| {

        let mut notes = Vec::new();

        a.authorize_in_time(&p, "origin", &old.refs[0], sa, &signer, lc, &mut notes)

            .map(|_| notes)

    };

    // Claimed inside the window, first witnessed an hour later, after

    // the certificate expired: backdated, or held back. Accepted by the

    // earlier rule while logs are new, with both said.

    let notes = judged(&sa, &at(3600)).unwrap();

    assert!(

        notes

            .iter()

            .any(|n| n.contains("had lapsed when witness w.example"))

            && notes

                .iter()

                .any(|n| n.contains("55 minutes before witness")),

        "{notes:?}"

    );

    // Claimed after the certificate expired, but witnessed inside its

    // window: the clock the signer did not choose decides. The gap is

    // still noted.

    let fast = attested(now);

    let notes = judged(&fast, &at(400)).unwrap();

    assert!(

        notes.len() == 1 && notes[0].contains("after witness w.example saw it"),

        "{notes:?}"

    );

    // Claimed and witnessed after it expired: refused, as before.

    assert!(judged(&fast, &at(3600)).is_err());

    // A gap within ten minutes is nothing to note.

    assert!(judged(&sa, &at(500)).unwrap().is_empty());

}

//!

//! The witnesses that cosign a hub's checkpoints are pinned the same way

//! (`<oxy home>/tlog/<hub>.witnesses`), and give each bookmark's

//! attestation an *integrated time* (oxygenhub#240): the earliest time a

//! trusted witness cosigned a checkpoint holding it. A fetch checks

//! delegations and certificates at that time when it has one.

use crate::tlog::{self, Checkpoint, Entry, Hash, HashReader, Integrated, Note, Tile, TlogError};

    pub(crate) fn remember_log(&self, hub: &str, identity: &Identity, note: &Note) -> Result<()> {

    ) -> Result<std::result::Result<Accepted, String>> {

        Ok(Ok(Accepted {

            checkpoint: cp,

            identity,

            note,

            notes,

        }))

    }

    fn witnesses_file(&self, hub: &str) -> PathBuf {

        let mut p = self.tlog_file(hub);

        p.set_file_name(format!("{}.witnesses", file_name(hub)));

        p

    }

    /// The witnesses this user pinned for `hub`: each one's name in

    /// cosignatures and its identity.

    pub(crate) fn pinned_witnesses(&self, hub: &str) -> Vec<(String, Identity)> {

        let Ok(text) = fs::read_to_string(self.witnesses_file(hub)) else {

            return vec![];

        };

        text.lines()

            .filter_map(|l| {

                let (name, key) = l.split_once(' ')?;

                let id = Identity::decode(&crate::dsse::base64_decode(key)?).ok()?;

                Some((name.to_string(), id))

            })

            .collect()

    }

    /// Pin the witnesses `hub` lists (name and identity bytes), as its log

    /// key is pinned: on first sight silently, later with a note for a

    /// witness that is new or has another key than before. A witness the

    /// hub no longer lists stays pinned. Returns every pinned witness.

    pub(crate) fn pin_witnesses(

        &self,

        hub: &str,

        listed: &[(String, Vec<u8>)],

        notes: &mut Vec<String>,

    ) -> Result<Vec<(String, Identity)>> {

        let path = self.witnesses_file(hub);

        let first = !path.exists();

        let mut pinned = self.pinned_witnesses(hub);

        let mut changed = false;

        for (name, bytes) in listed {

            if name.is_empty() || name.contains(char::is_whitespace) {

                notes.push(format!(

                    "{hub} lists a witness named {name:?}, which cannot name one"

                ));

                continue;

            }

            let Ok(id) = Identity::decode(bytes) else {

                notes.push(format!(

                    "{hub} lists witness {name} with a key that does not decode"

                ));

                continue;

            };

            match pinned.iter_mut().find(|(n, _)| n == name) {

                Some((_, old)) if old.hash() == id.hash() => {}

                Some((_, old)) => {

                    notes.push(format!(

                        "{hub}'s witness {name} has another key than before ({} now, {} then): if its operator did not announce one, {hub} may be naming a witness of its own",

                        id.hash().short(12),

                        old.hash().short(12)

                    ));

                    *old = id;

                    changed = true;

                }

                None => {

                    if !first {

                        notes.push(format!(

                            "{hub} is now cosigned by witness {name} (key {}), trusted from now on",

                            id.hash().short(12)

                        ));

                    }

                    pinned.push((name.clone(), id));

                    changed = true;

                }

            }

        }

        if changed {

            if let Some(dir) = path.parent() {

                fs::create_dir_all(dir)?;

            }

            let text: String = pinned

                .iter()

                .map(|(n, id)| format!("{n} {}\n", crate::dsse::base64(&id.encode())))

                .collect();

            crate::durable::write_atomic(&path, text.as_bytes())?;

        }

        Ok(pinned)

    /// Check what a refs answer from `url` says about its host's log, and

    /// read each bookmark attestation's integrated time. Fails only when

    /// the host showed two histories under one key; everything else is a

    /// note.

    ) -> Result<LogCheck> {

        let mut out = LogCheck::default();

            return Ok(out);

        out.kept = true;

        let accepted = match self.accept_checkpoint(&hub, text, &options)? {

                out.notes

                    .push(format!("{hub}'s transparency log was not checked: {why}"));

                out.unchecked = Some(why);

                return Ok(out);

        let cp = &accepted.checkpoint;

        out.notes.extend(accepted.notes.iter().cloned());

        let witnesses = self.pin_witnesses(&hub, &resp.witnesses, &mut out.notes)?;

                out.times

                    .insert(r.name.clone(), Err("it is not in the log yet".into()));

                out.notes.push(format!(

            let time = if !fits {

                Err("its log entry is not its attestation's".to_string())

            } else if witnesses.is_empty() {

                Err(format!("{hub} names no witness"))

            } else {

                let cosigned: Vec<(&str, &[Hash])> = r

                    .integration

                    .iter()

                    .map(|i| (i.note.as_str(), i.proof.as_slice()))

                    .collect();

                tlog::integrated_time(

                    &l.entry,

                    l.index,

                    &cosigned,

                    &cp.origin,

                    &accepted.identity,

                    &witnesses,

                )

            };

            out.times.insert(r.name.clone(), time);

            out.notes.push(format!(

        }

        Ok(out)

    }

}

/// A checkpoint `accept_checkpoint` took: the checkpoint, the log key it

/// verified with, its note as served, and what accepting it noted.

pub(crate) struct Accepted {

    pub checkpoint: Checkpoint,

    pub identity: Identity,

    pub note: Note,

    pub notes: Vec<String>,

}

/// What a refs answer said about its host's log.

#[derive(Debug, Default)]

pub(crate) struct LogCheck {

    /// Whether the host keeps a log (it sent a checkpoint).

    pub kept: bool,

    /// Why the log could not be checked, when it could not.

    pub unchecked: Option<String>,

    pub notes: Vec<String>,

    /// Each attested bookmark's integrated time, or why it has none.

    pub times: HashMap<String, std::result::Result<Integrated, String>>,

}

impl LogCheck {

    /// Bookmark `name`'s integrated time, or why there is none.

    pub fn time_of(&self, name: &str) -> std::result::Result<&Integrated, String> {

        if let Some(why) = &self.unchecked {

            return Err(format!("its host's log was not checked ({why})"));

        }

        if !self.kept {

            return Err("its host keeps no transparency log".into());

        match self.times.get(name) {

            Some(Ok(i)) => Ok(i),

            Some(Err(why)) => Err(why.clone()),

            None => Err("it has no log entry".into()),

        }

    }

}

/// How a check that depends on when an attestation was signed came out

/// (spec §14.8, *Integrated time*).

#[derive(Clone, Copy, Debug, PartialEq, Eq)]

pub(crate) enum Timed {

    /// Passed at the integrated time.

    Integrated,

    /// No integrated time: passed by the earlier rule (the issuer's

    /// acceptance, else the attestation's own time).

    Fallback,

    /// Failed at the integrated time but passed by the earlier rule:

    /// accepted with a note while logs are new.

    Disagrees,

    /// Failed.

    Refused,

}

/// Judge a check (`at`, made at a time in milliseconds) at the integrated

/// time when there is one, else by the earlier rule (`before`).

pub(crate) fn judge(

    integrated: Option<u64>,

    at: impl Fn(u64) -> bool,

    before: impl FnOnce() -> bool,

) -> Timed {

    match integrated {

        Some(t) if at(t) => Timed::Integrated,

        Some(_) => {

            if before() {

                Timed::Disagrees

            } else {

                Timed::Refused

            }

        }

        None => {

            if before() {

                Timed::Fallback

            } else {

                Timed::Refused

            }

        }

    }

}

/// A note when an attestation's claimed time (`claimed`, its own clock)

/// is more than `tlog::TIME_TOLERANCE_MS` from its integrated time.

pub(crate) fn gap_note(claimed: u64, integrated: &Integrated) -> Option<String> {

    let t = integrated.ms();

    let minutes = |d: u64| d.div_ceil(60_000);

    if claimed.saturating_add(tlog::TIME_TOLERANCE_MS) < t {

        Some(format!(

            "claims to be from {} minutes before witness {} first saw it: backdated, held back before it was logged, or signed on a slow clock",

            minutes(t - claimed),

            integrated.witness

        ))

    } else if claimed > t.saturating_add(tlog::TIME_TOLERANCE_MS) {

        Some(format!(

            "claims to be from {} minutes after witness {} saw it: signed on a fast clock",

            minutes(claimed - t),

            integrated.witness

        ))

    } else {

        None

    /// The trusted witnesses that cosigned the checkpoint, with their

    /// times in seconds, earliest first.

    pub witnessed: Vec<(String, u64)>,

        let accepted = match self.accept_checkpoint(&hub, &text, &options)? {

        let mut notes = accepted.notes;

        // The witnesses it names (one `<name> <base64 identity>` line

        // each), pinned as a fetch pins them; a hub that does not list

        // them leaves those pinned before.

        let listed: Vec<(String, Vec<u8>)> = http_get(&format!("{hub}/log/witnesses"), &options)

            .ok()

            .and_then(|b| String::from_utf8(b).ok())

            .map(|t| {

                t.lines()

                    .filter_map(|l| {

                        let (n, k) = l.split_once(' ')?;

                        Some((n.to_string(), crate::dsse::base64_decode(k.trim())?))

                    })

                    .collect()

            })

            .unwrap_or_default();

        let witnesses = self.pin_witnesses(&hub, &listed, &mut notes)?;

        let mut witnessed = accepted.note.cosignatures(&witnesses);

        witnessed.sort_by_key(|(_, t)| *t);

        let cp = accepted.checkpoint;

            witnessed,

// -------------------------------------------------------- integrated time

/// How far a claimed time may stray from an integrated time before it is

/// noted (spec §14.8, *Integrated time*): ten minutes, in milliseconds.

pub const TIME_TOLERANCE_MS: u64 = 10 * 60 * 1000;

impl Note {

    /// The witnesses among `trusted` (name and identity) whose

    /// cosignatures of this note verify, with their times in seconds.

    /// Lines by anyone else are ignored.

    pub fn cosignatures(&self, trusted: &[(String, Identity)]) -> Vec<(String, u64)> {

        trusted

            .iter()

            .filter_map(|(n, id)| self.cosigned_by(n, id).ok().map(|t| (n.clone(), t)))

            .collect()

    }

}

/// When witnesses first saw a log entry (spec §14.8): an upper bound on

/// when what it logs was signed, by a clock neither its signer nor the

/// log chose.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Integrated {

    /// The earliest trusted cosignature's time, in seconds.

    pub time: u64,

    /// The witness that made it.

    pub witness: String,

    /// The size of the checkpoint it cosigned.

    pub size: u64,

}

impl Integrated {

    /// The time in milliseconds, as Oxygen's other times are.

    pub fn ms(&self) -> u64 {

        self.time.saturating_mul(1000)

    }

}

/// Entry `index` (`entry`, its bytes)'s integrated time: the earliest time

/// a witness in `trusted` cosigned one of `cosigned` (checkpoint notes,

/// each with the entry's inclusion proof against it) that `log_key`

/// signed for `origin` and that includes the entry. A note that does not

/// verify, or does not include the entry, counts for nothing; `Err` says

/// why no time could be read.

pub fn integrated_time(

    entry: &[u8],

    index: u64,

    cosigned: &[(&str, &[Hash])],

    origin: &str,

    log_key: &Identity,

    trusted: &[(String, Identity)],

) -> std::result::Result<Integrated, String> {

    if cosigned.is_empty() {

        return Err("no witness has cosigned a checkpoint holding it yet".into());

    }

    let leaf = leaf_hash(entry);

    let mut best: Option<Integrated> = None;

    let mut why = String::new();

    for (text, proof) in cosigned {

        let checked = Note::parse(text)

            .and_then(|n| Checkpoint::verify(&n, origin, log_key).map(|c| (n, c)))

            .and_then(|(n, c)| {

                check_inclusion(proof, c.size, &c.root, index, &leaf)?;

                Ok((n, c))

            });

        let (note, cp) = match checked {

            Ok(x) => x,

            Err(e) => {

                why = format!("a cosigned checkpoint served for it does not hold it ({e})");

                continue;

            }

        };

        let times = note.cosignatures(trusted);

        if times.is_empty() {

            why = format!(

                "the checkpoint of {} entries holding it is cosigned by no witness this user trusts",

                cp.size

            );

            continue;

        }

        for (witness, time) in times {

            if best.as_ref().is_none_or(|b| time < b.time) {

                best = Some(Integrated {

                    time,

                    witness,

                    size: cp.size,

                });

            }

        }

    }

    best.ok_or(why)

}

    }

    #[test]

    fn an_entry_is_integrated_when_a_trusted_witness_first_cosigned_it() {

        let log_sk = SecretKey::generate();

        let log = log_sk.identity("log", "[email protected]", 1);

        let origin = "hub.example/log";

        let witness = |name: &str| {

            let sk = SecretKey::generate();

            (name.to_string(), sk.identity(name, "[email protected]", 1), sk)

        };

        let (a, b, c) = (

            witness("a.example"),

            witness("b.example"),

            witness("c.example"),

        );

        let trusted = vec![(a.0.clone(), a.1.clone()), (b.0.clone(), b.1.clone())];

        // A log of 40 real entries, so `integrated_time` hashes the leaf.

        let leaf_bytes = |n: u64| {

            Entry {

                kind: "ref".into(),

                repo: [n as u8; 16],

                object: ObjectRef([n as u8; 32]),

                signers: vec![],

                received: n,

            }

            .encode()

        };

        let mut stored: Vec<Hash> = Vec::new();

        for n in 0..40 {

            let add = stored_hashes_for_leaf(n, leaf_hash(&leaf_bytes(n)), &stored).unwrap();

            stored.extend(add);

        }

        // Checkpoint `n`, cosigned by each of `by` at its time.

        type W = (String, Identity, SecretKey);

        let cosigned = |n: u64, by: &[(&W, u64)]| {

            let cp = Checkpoint {

                origin: origin.into(),

                size: n,

                root: tree_hash(n, &stored).unwrap(),

                extensions: vec![],

            };

            let mut note = cp.sign(&log, &log_sk).unwrap();

            for ((name, id, sk), t) in by {

                note.sigs

                    .extend(cosign(&note.text, name, id, sk, *t).unwrap());

            }

            note.encode()

        };

        let proof = |n: u64| prove_inclusion(n, 7, &stored).unwrap();

        let entry = leaf_bytes(7);

        let time = |served: &[(String, Vec<Hash>)]| {

            let s: Vec<(&str, &[Hash])> = served

                .iter()

                .map(|(n, p)| (n.as_str(), p.as_slice()))

                .collect();

            integrated_time(&entry, 7, &s, origin, &log, &trusted)

        };

        // One checkpoint, two witnesses: the earlier cosignature.

        let one = cosigned(10, &[(&a, 1_792_300_050), (&b, 1_792_300_020)]);

        let got = time(&[(one.clone(), proof(10))]).unwrap();

        assert_eq!(

            (got.time, got.witness.as_str(), got.size),

            (1_792_300_020, "b.example", 10)

        );

        assert_eq!(got.ms(), 1_792_300_020_000);

        // Witnesses that first cosigned different checkpoints: the

        // earliest of all.

        let later = cosigned(20, &[(&a, 1_792_300_010)]);

        let got = time(&[(later.clone(), proof(20)), (one.clone(), proof(10))]).unwrap();

        assert_eq!(

            (got.time, got.witness.as_str()),

            (1_792_300_010, "a.example")

        );

        // A witness this user does not trust is no witness, however early.

        let stranger = cosigned(10, &[(&c, 1)]);

        let err = time(&[(stranger, proof(10))]).unwrap_err();

        assert!(err.contains("no witness this user trusts"), "{err}");

        // A forged cosignature under a trusted name: c's key signed it.

        let forged = cosigned(10, &[(&(a.0.clone(), c.1.clone(), c.2.clone()), 1)]);

        assert!(time(&[(forged.clone(), proof(10))]).is_err());

        // Beside a real one, it changes nothing.

        let got = time(&[(forged, proof(10)), (one.clone(), proof(10))]).unwrap();

        assert_eq!(got.time, 1_792_300_020);

        // A time moved after cosigning no longer verifies.

        let mut moved = Note::parse(&one).unwrap();

        for s in moved.sigs.iter_mut().filter(|s| s.name == "b.example") {

            s.sig[..8].copy_from_slice(&1u64.to_be_bytes());

        }

        let got = time(&[(moved.encode(), proof(10))]).unwrap();

        assert_eq!(got.witness, "a.example", "b's lines no longer verify");

        // A checkpoint that does not hold the entry, a proof for another

        // size, another log's key: no time.

        let early = cosigned(5, &[(&a, 1)]);

        assert!(time(&[(early, proof(10))]).is_err());

        assert!(time(&[(one.clone(), proof(20))]).is_err());

        let other_sk = SecretKey::generate();

        let other = other_sk.identity("x", "x@x", 1);

        let s = [(one.as_str(), proof(10))];

        let s: Vec<(&str, &[Hash])> = s.iter().map(|(n, p)| (*n, p.as_slice())).collect();

        assert!(integrated_time(&entry, 7, &s, origin, &other, &trusted).is_err());

        assert!(integrated_time(&entry, 7, &s, "elsewhere/log", &log, &trusted).is_err());

        assert!(integrated_time(&leaf_bytes(8), 7, &s, origin, &log, &trusted).is_err());

        // Nothing served.

        assert!(time(&[]).unwrap_err().contains("no witness has cosigned"));

- A reference attestation's signer is authorized by a rule if the rule lists it, or lists an identity whose `delegates` name it with the `refs` scope, not expired at the attestation's `hlc.wall_ms` (§14.2), or, on a fetch, at its integrated time when the host's log gives one (§14.8). Delegation is the identity's own signed statement and the policy names that identity, so a delegate with `refs` moves references exactly as far as its delegator may; revoking either key, or the delegation expiring, ends it. Hosts use this to land and to commit browser edits on a user's behalf with their own key. A delegate without `refs` (an agent) is never authorized for a reference or tag, even when its delegator is.

- A rule may also grant **subjects an issuer certifies** (§14.7): `oxy policy grant-subject SUBJECT --issuer IDENTITY --scope SCOPES` adds `{pattern, issuer, scope}` and embeds the issuer's identity. A signer is then authorized when it is a short-lived key whose certificate verifies with that issuer, names a subject the pattern matches, gives the scope needed (`changes` for changes, `refs` for reference attestations and tags) and covers a time the signer did not choose; it counts as one signer toward the threshold. A rule with subjects only has no keys, and its threshold counts keys and subjects together. The time is the receiver's own clock when it receives a push (changes and the reference attestation), and, on a fetch, the attestation's integrated time when the host's log gives one (§14.8, *Integrated time*); without one, the time the certificate's issuer says it accepted the update (§14.7, *Acceptance*), or the attestation's own time when there is no such acceptance, which is weaker: a key whose certificate expired could backdate an attestation within its scope. A policy without subjects encodes as before (field 5 is left out), so its hash is unchanged.

**Acceptance.** A host that issues certificates records when it accepted a reference attestation signed by a short-lived key: an `accepted` attestation (§14.4) naming that attestation's ObjectRef, its `hlc` the host's clock at the push, signed in domain `attest` by the issuer's key. The host keeps it indexed by the attestation it accepts (gc keeps it beside the bookmark's latest attestation) and serves it with the bookmark (§16, `refs` key 5). A fetch checks the certificate at the acceptance's time only when the acceptance names exactly the attestation being checked and verifies with the certificate's issuer; otherwise, including when there is none, at the attestation's own time. An acceptance by any other key changes nothing: the issuer is already trusted to vouch for the key, so it adds no trust it did not have. A fetch that has the attestation's integrated time (§14.8) checks at that instead: the acceptance is the issuer's clock, the integrated time its witnesses'.

**Integrated time** (oxygenhub#240). A cosignature is a witness's statement, by its own clock, that the checkpoint existed then, so every entry the checkpoint holds existed by that time, whatever its signer or the host claims. An entry's **integrated time** is the earliest time a witness the reader trusts cosigned a checkpoint that holds it: an upper bound on when its object was signed, in seconds, by a clock neither the signer nor the host chose.

- **Witness keys.** A host lists the witnesses it asks to cosign, each as its name in cosignatures and its identity (refs response key 7, §16.3; and `GET /log/witnesses`, one `<name> <base64 identity>` line each). A client pins them per user and hub beside the log key (`<oxy home>/tlog/<hub>.witnesses`): the first list silently, as the log key on first sight; a witness listed later, or listed under a pinned name with another key, is pinned with a note, as a new log key is. A witness the host stops listing stays pinned. A cosignature counts only when both its lines verify with a pinned witness's key; lines by anyone else are ignored. Trust-on-first-use gives no more than the host's own word on first contact, which is what the acceptance gives today (§14.7); after it, a host that names a witness of its own to move a time earlier is noted by every client that pinned the real ones.

- **What a host serves.** With a bookmark's entry (ref key 6), the cosigned checkpoints that first held it (ref key 7): each a checkpoint note with the log's signatures and its witnesses' cosignatures, and the entry's inclusion proof against it, one for each witness when they first cosigned different checkpoints. A client takes one when its origin is the log's, it verifies with the pinned log key, the entry is the attestation's (as above) and the proof verifies; the integrated time is the earliest trusted cosignature among those it takes. A host can only make the time later by serving a later checkpoint, which weakens the bound and helps no one but a signer it would refuse; it cannot make it earlier without a witness's key.

- **Use.** On a fetch, a check that depends on when a reference attestation was signed (whether a delegation with `refs` was in force, §14.5, or whether a certificate covered it, §14.7) is made at the integrated time when there is one. Without one (the host keeps no log, the entry is in no cosigned checkpoint yet, or no trusted witness cosigned it), it is made as before, at the issuer's acceptance or the attestation's own time, and the fetch says so when the host keeps a log. While logs are new (oxygenhub docs/transparency.md, decision 3), an attestation that fails at its integrated time but passes as before is accepted with a note rather than refused; one that fails both is refused, as before. A key the rule lists itself is authorized whenever it signed, and revocations are absolute (§14.5): neither depends on the time. A push is checked at the receiver's own clock, as before.

- **A large gap.** For an attestation whose check depends on the time, a claimed time (`hlc.wall_ms`) more than 10 minutes before its integrated time, or more than 10 minutes after it, is noted, not refused: the attestation was backdated, held back before it was logged (one a host accepted before its log began, logged when first served), or signed on a wrong clock. A reference attestation is made at push and logged and cosigned within seconds, so ten minutes leaves room for drift and for a witness that was briefly away.

**`oxy tlog verify [HUB]`** audits a whole log: it accepts the checkpoint as a fetch does, downloads every entry bundle, and requires the entries to make the root the checkpoint signs. It names the trusted witnesses that cosigned the checkpoint and when (pinning those `GET /log/witnesses` lists, as a fetch does), a bound on when every entry was made. It then lists this repository's entries (`--key KEYID` for a key's, `--all` for every one, `--json` for machines).

| `refs` response | `{0: [{0: name, 1: state ref, 2: [heads], 3: signed attestation or null, 4: last serial or null, 5: signed acceptance}], 1: repo id, 2: signed policy or null, 3: [tag], 4: [signed policy]}`; key 4 (optional) lists earlier policies ascending by serial; key 5 (optional, text or null) names the default bookmark, which a clone checks out; the attestation is present only when it describes the current state; an entry's key 5 (optional, only when there is one) is the host's acceptance of that attestation (§14.7); an entry's key 6 (optional) is the attestation's place in the host's transparency log, `[entry number, entry bytes, [proof hash]]`, an inclusion proof against the checkpoint in the response's key 6 (§14.8); an entry's key 7 (optional, only beside key 6 and when there are any) lists the cosigned checkpoints that first held that log entry, `[[checkpoint note text, [proof hash]]]`, each with the entry's inclusion proof against it, from which its integrated time is read (§14.8); the response's key 6 (optional, text) is the host's latest checkpoint, a signed note; the response's key 7 (optional, only when there are any) lists the witnesses the host asks to cosign, `[[name, identity bytes]]`, which a client pins (§14.8); a tag is `{0: name, 1: state ref, 2: [heads], 3: signed attestation or null}` |