Keyless agents create release tags: receive and fetch authorize certified tag keys 1ec6fdbc6bcb

- **Keyless agents can create release tags (#129).** `oxy tag create` and `oxy push` under a keyless home was refused "unknown key": the push did not carry the tag signer's identity and certificate, and tags were authorized only by keys the policy names, never by a certificate under a subject grant. The push now carries them, and a receiver authorizes a short-lived key's tag by a subject grant at its own clock, as it does a bookmark move, and records when it accepted it (OxygenHub signs that with its key). A fetch checks such a tag at that acceptance, or at its integrated time when the hub's log gives one, so a release tag made with a ten-minute key is still fetched months later. A fetch never checks it at the time the tag claims: without an acceptance the tag is left out with a warning (`tags/NAME not updated`), and the rest is fetched. A client keeps the acceptance and serves and pushes it with the tag, so a tag passed on to another remote, or cloned from a clone, keeps its time. The wire change is additive: tags in `refs` and `push` gain keys 4 to 6 (acceptance, log place, cosigned checkpoints), which older readers ignore.

    /// The acceptance of `attestation` by its signer's certificate issuer

    /// when a short-lived key signed it (spec §14.7; key 4, only when there

    /// is one): the time a fetch checks the certificate at.

    pub accepted: Option<SignedAttest>,

    /// The attestation's place in the host's transparency log (key 5,

    /// only when it has one), as a bookmark's.

    pub logged: Option<Logged>,

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

    /// 6, only when there are any).

    pub integration: Vec<Integration>,

}

impl TagRef {

    /// A tag with no acceptance or log place (yet).

    pub fn new(

        name: String,

        state: ObjectRef,

        heads: Vec<ChangeHash>,

        attestation: Option<SignedAttest>,

    ) -> TagRef {

        TagRef {

            name,

            state,

            heads,

            attestation,

            accepted: None,

            logged: None,

            integration: vec![],

        }

    }

                    let mut v = Value::map([

                    ]);

                    // Only when there is one; older peers ignore them

                    // (oxygen#129).

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

                        if t.accepted.is_some() {

                            m.insert(4, opt_attest_value(&t.accepted));

                        }

                        if let Some(l) = &t.logged {

                            m.insert(5, logged_value(l));

                        }

                        if !t.integration.is_empty() {

                            m.insert(6, integration_value(&t.integration));

                        }

                    }

                    v

                accepted: match tm.get(&4) {

                    Some(a) => opt_attest_from(a)?,

                    None => None,

                },

                logged: tm.get(&5).map(logged_from).transpose()?,

                integration: match tm.get(&6) {

                    Some(l) => integration_from(l)?,

                    None => Vec::new(),

                },

        }

        Ok(out)

    }

    /// The tags of a refs answer as oxy 0.5.0 read them (and the runners

    /// built with it), keys 0 to 3 only: what an older reader makes of an

    /// answer with keys 4 to 6.

    #[cfg(test)]

    pub(super) fn tags_as_0_5_read_them(bytes: &[u8]) -> Result<Vec<TagRef>> {

        let v = cbor::decode(bytes).map_err(ObjectError::from)?;

        let m = map(&v, "refs")?;

        let mut out = Vec::new();

        for t in o::array(field(m, 3, "tags")?, "tags")? {

            let tm = map(t, "tag")?;

            out.push(TagRef::new(

                o::text(field(tm, 0, "name")?, "name")?.to_owned(),

                o::oref(field(tm, 1, "state")?, "state")?,

                hashes_from(field(tm, 2, "heads")?)?,

                opt_attest_from(field(tm, 3, "attestation")?)?,

            ));

    }

    /// A log place, `[entry number, entry bytes, [proof hash]]` (spec §14.8).

    fn logged_value(l: &Logged) -> Value {

        Value::Array(vec![

            Value::Uint(l.index),

            Value::Bytes(l.entry.clone()),

            proof_value(&l.proof),

        ])

    fn logged_from(v: &Value) -> Result<Logged> {

        let a = o::array(v, "logged")?;

        if a.len() != 3 {

            return Err(schema("logged: expected [index, entry, proof]"));

        }

        Ok(Logged {

            index: o::uint(&a[0], "index")?,

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

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

        })

    }

    /// Cosigned checkpoints holding an entry, `[[note, [proof hash]]]`.

    fn integration_value(integration: &[Integration]) -> Value {

        Value::Array(

            integration

                .iter()

                .map(|i| Value::Array(vec![Value::Text(i.note.clone()), proof_value(&i.proof)]))

                .collect(),

        )

    }

    fn integration_from(v: &Value) -> Result<Vec<Integration>> {

        let mut out = Vec::new();

        for i in o::array(v, "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])?,

            });

        }

        Ok(out)

    }

                                    m.insert(6, logged_value(l));

                                    m.insert(7, integration_value(&r.integration));

                logged: rm.get(&6).map(logged_from).transpose()?,

                    Some(l) => integration_from(l)?,

        let tag = TagRef::new("v1".into(), ObjectRef([2; 32]), vec![c.hash()], None);

        // A tag's acceptance and log place (oxygen#129): keys 4 to 6, only

        // when there are any, so a tag without them encodes as before.

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

            panic!()

        };

        let crate::cbor::Value::Array(tags) = &m[&3] else {

            panic!()

        };

        let crate::cbor::Value::Map(plain) = &tags[0] else {

            panic!()

        };

        assert_eq!(plain.keys().copied().collect::<Vec<_>>(), vec![0, 1, 2, 3]);

        let mut full = tag.clone();

        full.name = "v2".into();

        full.attestation = Some(SignedAttest {

            attest: att.clone(),

            sigs: vec![sig.clone()],

        });

        full.accepted = full.attestation.clone();

        full.logged = Some(Logged {

            index: 7,

            entry: vec![4],

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

        });

        full.integration = vec![Integration {

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

            proof: vec![],

        }];

        resp.tags = vec![full.clone(), tag.clone()];

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

        assert_eq!(wire::decode_refs(&bytes).unwrap().1.tags, resp.tags);

        // In a push too.

        let pushed = wire::encode_push(&Bundle::default(), &[], None, &resp.tags);

        assert_eq!(wire::decode_push(&pushed).unwrap().3, resp.tags);

        // A reader that knows only keys 0 to 3 (oxy 0.5.0 and older, and

        // the runners built with it) reads the same tags from the new answer.

        let stripped: Vec<TagRef> = resp

            .tags

            .iter()

            .map(|t| {

                TagRef::new(

                    t.name.clone(),

                    t.state,

                    t.heads.clone(),

                    t.attestation.clone(),

                )

            })

            .collect();

        assert_eq!(wire::tags_as_0_5_read_them(&bytes).unwrap(), stripped);

                // With its issuer's acceptance (spec §14.7).

                if let Some(acc) = self.acceptance_of(&r)? {

                    attests.push(acc.attest.hash());

                }

                .adopt_tag(

                    &mut view,

                    t,

                    policy.as_ref(),

                    &mut super::tags::TagCheck::Mirrored,

                )

                .map_err(|e| RepoError::Msg(format!("{}: {}", self.what(), e.reason)))?;

use super::tags::TagCheck;

            match self.adopt_tag(&mut view, t, policy.as_ref(), &mut TagCheck::Received) {

                    reason: e.reason,

        self.issuer_acceptance(signer, sa, accepted)

            .unwrap_or(sa.attest.hlc.wall_ms)

    }

    /// The time of `accepted` when it accepts exactly `sa` and is signed by

    /// the issuer of `signer`'s kept certificate (spec §14.7); else none.

    pub(crate) fn issuer_acceptance(

        &self,

        signer: &KeyId,

        sa: &SignedAttest,

        accepted: Option<&SignedAttest>,

    ) -> Option<u64> {

        let acc = accepted?;

        let c = self.store.certificate_of(signer).ok().flatten()?;

        let cert = self.store.get_certificate(&c).ok()?;

            return None;

        let sig = acc.sigs.iter().find(|s| s.key == cert.cert.issuer)?;

        let issuer = self.store.get_identity(&cert.cert.issuer).ok()?;

        (*attest == sa.attest.hash()

            && verify_signature(&issuer, sig, Domain::Attest, &acc.attest.hash()).is_ok())

        .then_some(acc.attest.hlc.wall_ms)

    }

    /// Keep an acceptance this repository was given for attestation `r`

    /// (one [`Repo::issuer_acceptance`] took), so it is served again with

    /// what it accepts.

    pub(crate) fn keep_acceptance(&self, r: &ObjectRef, acc: &SignedAttest) -> Result<()> {

        let a = self.store.put_attest(&acc.attest)?;

        for sig in &acc.sigs {

            self.store.put_signature(&a, sig)?;

        self.store.index_add_pub("accepted", r, &a)?;

        Ok(())

            let mut check = TagCheck::Fetched {

                remote: remote_name,

                log: &log,

                notes: &mut log_notes,

            };

            match self.adopt_tag(&mut view, t, policy.as_ref(), &mut check) {

                Ok(()) => new_tags += 1,

                // Nothing says when a short-lived key signed it: the tag is

                // left out, said so, and the rest is fetched (oxygen#129).

                Err(e) if e.untimed => {

                    skipped.push((format!("tags/{}", t.name), e.reason));

                }

                Err(e) => return fail(format!("{remote_name} {}: {}", t.name, e.reason)),

            }

/// How a tag's signer is judged when it is adopted (spec §10.1, §14.7).

pub(crate) enum TagCheck<'a> {

    /// Received in a push: a short-lived key's certificate is checked at

    /// the receiver's own clock, or at its issuer's acceptance when the

    /// push carries one (a tag passed on from another host).

    Received,

    /// Fetched from `remote`: at the tag attestation's integrated time when

    /// the host's log gives one, else at its certificate issuer's

    /// acceptance; never at the time the tag claims, which its signer chose.

    Fetched {

        remote: &'a str,

        log: &'a super::transparency::LogCheck,

        notes: &'a mut Vec<String>,

    },

    /// Replayed into a Strata mirror from its store's record: at the

    /// acceptance when there is one, else at the tag's own time. The fetch

    /// from the mirror then judges it as every fetch does.

    Mirrored,

}

/// Why a tag was not adopted.

#[derive(Debug)]

pub(crate) struct TagRefusal {

    pub reason: String,

    /// Signed by a short-lived key, with nothing that says when to check

    /// its certificate: a fetch leaves the tag out and goes on.

    pub untimed: bool,

}

impl From<String> for TagRefusal {

    fn from(reason: String) -> TagRefusal {

        TagRefusal {

            reason,

            untimed: false,

        }

    }

}

impl From<&str> for TagRefusal {

    fn from(reason: &str) -> TagRefusal {

        reason.to_string().into()

    }

}

            // A short-lived key's tag goes with its issuer's acceptance

            // (spec §14.7), for whoever fetches it later.

            let accepted = match &attestation {

                Some(a) => self.tag_acceptance(a)?,

                None => None,

            };

            let mut tag = crate::protocol::TagRef::new(t.name, t.state, t.heads, attestation);

            tag.accepted = accepted;

            out.push(tag);

    }

    /// The acceptance kept for tag attestation `sa`: its signer's

    /// certificate issuer's when one of those kept is, else the first.

    fn tag_acceptance(&self, sa: &SignedAttest) -> Result<Option<SignedAttest>> {

        let r = sa.attest.hash();

        let mut first = None;

        for a in self.store.index_get_pub("accepted", &r)? {

            let acc = SignedAttest {

                attest: self.store.get_attest(&a)?,

                sigs: self.store.signatures(&a)?,

            };

            let signer = sa.sigs.first().map(|s| s.key);

            if signer.is_some_and(|k| self.issuer_acceptance(&k, sa, Some(&acc)).is_some()) {

                return Ok(Some(acc));

            }

            first.get_or_insert(acc);

        }

        Ok(first)

    /// A short-lived key's tag is authorized by a subject grant, its

    /// certificate checked at the time `check` says (spec §14.7), and its

    /// issuer's acceptance is kept with it, or recorded when this host

    /// receives it.

        check: &mut TagCheck,

    ) -> std::result::Result<(), TagRefusal> {

                )

                .into())

                )

                .into());

            let certified = self.store.certificate_of(&sig.key).ok().flatten().is_some();

            // The issuer's acceptance this tag came with, when it is one.

            let accepted = self.issuer_acceptance(&sig.key, sa, t.accepted.as_ref());

                let listed = p.authorizes(&sig.key, &reference)

                    || self.delegate_authorized(p, &sig.key, &reference, at)

                    || self.predecessor_authorized(p, &sig.key, &reference, at);

                if !listed

                    && !(certified

                        && self.tag_certified_in_time(p, t, sa, &sig.key, accepted, check)?)

                    )

                    .into());

            if certified {

                match (&t.accepted, accepted) {

                    (Some(acc), Some(_)) => self.keep_acceptance(&stored, acc),

                    // Received here: this host says when, as it does for a

                    // bookmark's attestation.

                    _ if matches!(check, TagCheck::Received) => self.record_acceptance(&stored),

                    _ => Ok(()),

                }

                .map_err(|e| e.to_string())?;

            }

            )

            .into());

    }

    /// Whether short-lived key `signer`'s certificate gives it tag `t`

    /// under policy `p` at the time `check` says (spec §14.7, §14.8):

    /// `accepted` is the issuer's acceptance time the tag came with.

    fn tag_certified_in_time(

        &self,

        p: &crate::policy::Policy,

        t: &crate::protocol::TagRef,

        sa: &SignedAttest,

        signer: &KeyId,

        accepted: Option<u64>,

        check: &mut TagCheck,

    ) -> std::result::Result<bool, TagRefusal> {

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

        let reference = format!("tags/{}", t.name);

        let certified = |ms: u64| self.certified_authorized(p, signer, &reference, Scope::REFS, ms);

        Ok(match check {

            TagCheck::Received => certified(Hlc::now().wall_ms) || accepted.is_some_and(certified),

            TagCheck::Mirrored => certified(accepted.unwrap_or(sa.attest.hlc.wall_ms)),

            TagCheck::Fetched { remote, log, notes } => {

                let time = log.tag_time_of(&t.name);

                let integrated = time.as_ref().ok().map(|i| i.ms());

                if integrated.is_none() && accepted.is_none() {

                    return Err(TagRefusal {

                        reason: format!(

                            "signed by short-lived key {}, and {remote} gave no time to check its certificate at (neither its issuer's acceptance nor a witnessed log time: {}); a tag is never checked at the time it claims",

                            signer.short(12),

                            time.err().unwrap_or_default()

                        ),

                        untimed: true,

                    });

                }

                let what = format!("{remote} tag {}", t.name);

                match judge(integrated, certified, || accepted.is_some_and(certified)) {

                    Timed::Refused => false,

                    Timed::Integrated => true,

                    Timed::Disagrees => {

                        notes.push(format!(

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

                            signer.short(12),

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

                        ));

                        true

                    }

                    Timed::Fallback => {

                        if log.kept {

                            notes.push(format!(

                                "{what}: {} checked at the issuer's acceptance, not at a witnessed time: {}",

                                signer.short(12),

                                time.err().unwrap_or_default()

                            ));

                        }

                        true

                    }

                }

            }

        })

    assert!(

        host.store().get_identity(&first).is_err(),

        "the host has never seen the tag's key"

    );

    assert!(r.iter().all(|x| x.ok), "{r:?}");

    let host = Repo::open(&root.join("origin")).unwrap();

    assert!(

        host.tag_refs().unwrap().iter().any(|t| t.name == "v1"),

        "the tag arrived"

    );

}

/// oxygen#129: a short-lived key's tag is checked on a fetch at a time its

/// signer did not choose, its issuer's acceptance, never at the time it

/// claims nor at the fetch's (when the ten-minute certificate has long

/// expired). Without an acceptance it is left out and said so; with one

/// inside the certificate's window it is fetched however much later, and

/// a host it is pushed on to keeps and serves the acceptance.

#[test]

fn a_short_lived_key_s_tag_is_fetched_at_its_issuer_s_acceptance() {

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

    use crate::identity::Scope;

    hermetic();

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

    let root = dir.path();

    let _origin = Repo::init(&root.join("origin")).unwrap();

    let url = root.join("origin").to_string_lossy().to_string();

    let mut a = Repo::clone(&url, &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();

    assert!(a.push("origin", false).unwrap().iter().all(|r| r.ok));

    let hub_sk = SecretKey::generate();

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

    a.policy_grant_subject(

        "agent:claude@ada",

        hub.clone(),

        Scope::CHANGES | Scope::REFS,

        Some("*"),

    )

    .unwrap();

    assert!(a.push("origin", false).unwrap().iter().all(|r| r.ok));

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

    // An agent whose key the hub certified from `from` to `to`.

    let agent = |name: &str, from: u64, to: u64| {

        let mut r = Repo::clone(&url, &root.join(name))

            .unwrap()

            .with_home(root.join(format!("home-{name}")));

        r.store().put_identity(&hub).unwrap();

        let (_, id) = r

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

            .unwrap();

        let cert = SignedCertificate::sign(

            Certificate {

                key: id,

                issuer: hub.hash(),

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

                claims: vec![],

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

                not_before: from,

                expires: to,

                grant: None,

            },

            &hub,

            &hub_sk,

        );

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

        r

    };

    // A tag by a key certified now, pushed to a host that records no

    // acceptance (a path on disk): it lands, but a fetch has no time to

    // check its certificate at, so it is left out and the fetch goes on.

    let claude = agent("claude", now - 60_000, now + 600_000);

    let heads = claude.bookmark_heads().unwrap();

    claude.tag_create("v1", &heads, "one").unwrap();

    let r = claude.push("origin", false).unwrap();

    let b = Repo::clone(&url, &root.join("b"))

        .unwrap()

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

    let rep = b.fetch("origin").unwrap();

    assert!(

        rep.skipped

            .iter()

            .any(|(n, why)| n == "tags/v1" && why.contains("no time to check its certificate at")),

        "{rep:?}"

    );

    assert_eq!(b.tag_heads("v1").unwrap(), None);

    // The host's acceptance, signed by the certificate's issuer, served

    // with the tag: fetched.

    let host = Repo::open(&root.join("origin"))

        .unwrap()

        .with_acceptor(hub.clone(), hub_sk.clone());

    let (v1, _) = host.tag_attest("v1").unwrap().unwrap();

    host.record_acceptance(&v1).unwrap();

    let served = host.tag_refs().unwrap();

    assert!(served

        .iter()

        .any(|t| t.name == "v1" && t.accepted.is_some()));

    let rep = b.fetch("origin").unwrap();

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

    assert_eq!(b.tag_heads("v1").unwrap(), Some(heads.clone()));

    // gc keeps the acceptance with the tag.

    host.gc(true).unwrap();

    assert!(host.acceptance_of(&v1).unwrap().is_some());

    // Long after: a key whose certificate expired an hour ago may not

    // create a tag now.

    let late = agent("late", now - 7_200_000, now - 3_600_000);

    late.tag_create("v2", &heads, "two").unwrap();

    let r = late.push("origin", false).unwrap();

    assert!(

        r.iter()

            .any(|x| x.name == "tags/v2" && !x.ok && x.reason.contains("may not create")),

        "{r:?}"

    );

    // With its issuer's acceptance from inside the window (as a hub gave

    // it then, passed on to another host), it is taken at that time: by

    // the host it is pushed to, which keeps it, and by a fresh clone.

    let (v2, _) = late.tag_attest("v2").unwrap().unwrap();

    let acc = Attest {

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

        hlc: Hlc {

            wall_ms: now - 5_400_000,

            logical: 0,

        },

        body: AttestBody::Accepted { attest: v2 },

    };

    let sig = hub_sk.sign(Domain::Attest, &hub.hash(), &acc.hash());

    // One by any other key gives no time.

    let stranger_sk = SecretKey::generate();

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

    let forged = stranger_sk.sign(Domain::Attest, &stranger.hash(), &acc.hash());

    late.keep_acceptance(

        &v2,

        &SignedAttest {

            attest: acc.clone(),

            sigs: vec![forged],

        },

    )

    .unwrap();

    let r = late.push("origin", false).unwrap();

    assert!(

        r.iter().any(|x| x.name == "tags/v2" && !x.ok),

        "not the issuer's: {r:?}"

    );

    let theirs = SignedAttest {

        attest: acc,

        sigs: vec![sig],

    };

    // Kept beside the stranger's: the issuer's is the one sent.

    late.keep_acceptance(&v2, &theirs).unwrap();

    let r = late.push("origin", false).unwrap();

    // (Its re-attestation of main is refused: an expired key moves no

    // bookmark.)

    assert!(r.iter().any(|x| x.name == "tags/v2" && x.ok), "{r:?}");

    let (hv2, _) = host.tag_attest("v2").unwrap().unwrap();

    assert_eq!(hv2, v2);

    assert!(host

        .store()

        .index_get_pub("accepted", &v2)

        .unwrap()

        .contains(&theirs.attest.hash()));

    let c = Repo::clone(&url, &root.join("c"))

        .unwrap()

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

    assert_eq!(c.tag_heads("v2").unwrap(), Some(heads.clone()));

    assert_eq!(c.tag_heads("v1").unwrap(), Some(heads));

    let unattested = crate::protocol::TagRef::new(

        "v3".into(),

        origin

        vec![h2],

        None,

    );

        // Each attestation's place in the log, and its integrated time.

        let mut place = |name: &str,

                         kind: &str,

                         a: &SignedAttest,

                         logged: Option<&crate::protocol::Logged>,

                         integration: &[crate::protocol::Integration]|

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

            let Some(l) = logged else {

                return Err("it is not in the log yet".into());

                e.kind == kind && e.object == a.attest.hash() && e.repo == a.attest.repo

                    "{hub}'s log entry {} for {name} does not prove its attestation is in the log",

                    l.index

            if !fits {

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

            }

        };

        let mut times = HashMap::new();

        for r in &resp.refs {

            let Some(a) = &r.attestation else { continue };

            let time = place(&r.name, "ref", a, r.logged.as_ref(), &r.integration);

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

        }

        // Tags too (oxygen#129): a short-lived key's tag is checked at its

        // integrated time on every later fetch.

        let mut tag_times = HashMap::new();

        for t in &resp.tags {

            let Some(a) = &t.attestation else { continue };

            let name = format!("tags/{}", t.name);

            let time = place(&name, "tag", a, t.logged.as_ref(), &t.integration);

            tag_times.insert(t.name.clone(), time);

        out.times = times;

        out.tag_times = tag_times;

    /// Each attested tag's, by tag name.

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

        self.lookup(&self.times, name)

    }

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

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

        self.lookup(&self.tag_times, name)

    }

    fn lookup<'a>(

        &self,

        times: &'a HashMap<String, std::result::Result<Integrated, String>>,

        name: &str,

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

        match times.get(name) {

| tag | `{0: name, 1: state ref, 2: [heads], 3: signed attestation or null, 4: signed acceptance, 5: log place, 6: [cosigned checkpoint]}`; keys 4 to 6 (optional, each only when there is one; oxygen#129) are for the tag's attestation what a ref's keys 5 to 7 are for its own: the issuer's `accepted` attestation when a short-lived key signed the tag (spec §14.7), which a fetch checks the certificate at, and its place in the host's transparency log with the cosigned checkpoints that first held it (spec §14.8); a push carries key 4 when the client has one; older readers ignore them |

Tags are attestations of kind `tag` and are never updated; a server MUST reject a second attestation for an existing tag name, and any receiver MUST refuse a tag whose name it already holds with a different state. `oxy tag create NAME [CHANGE..]` tags the named state (default the bookmark's heads); tags travel with `refs` and `push` (§16.3), and a policy rule for `tags/<name>` governs who may create them. A tag signed by a short-lived key (§14.7), as a keyless agent's is, is authorized by a subject grant like a bookmark update: on a push at the receiver's clock, on a fetch at a time its signer did not choose (§14.7, *Acceptance*). The push carries the tag signer's identity and certificate as it does the bookmark signer's, since the tag may have been made by an earlier process's key (oxygen#129).

- 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 tag is never checked at its own time: a fetch without an integrated time or an acceptance for it leaves the tag out and says why, and fetches the rest (oxygen#129). 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 or tag 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 or the tag's) and serves it with the bookmark (§16, `refs` entry key 5) or the tag (tag key 4). 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 for a bookmark, and not at all for a tag, which is left out (§14.5). Tags are kept for good and fetched long after a ten-minute certificate expired, so the issuer's acceptance travels with the tag: a client that fetched one keeps it and serves it with the tag, a push carries it, and a receiver checks a tag that comes with its issuer's acceptance at that time when its own clock is past the certificate's window (a tag passed on from the host that accepted it to another), keeping the acceptance rather than recording its own. 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'.

- **Use.** On a fetch, a check that depends on when a reference or tag 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 (for a tag, at the acceptance only, §14.7), 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.

| `Bundle` | `{0: [[change bytes, [Signature]]], 1: [signed attestation], 2: [[type name, object bytes]], 3: [signed policy]}`; changes in dependency order; objects are chunks, blobs, identities, and states only, and include the text blobs of every change in the bundle and their chunks, so a bundle can be read on its own; a push that moves a bookmark also carries the identity that signed the move and, for a delegate, the identity it acts for, so a receiver that has seen no change by that key can check it (oxygenhub#129), and a push that sends tags carries each tag signer's identity and, for a short-lived key, its certificate likewise (oxygen#129); key 3 (optional) holds the policies between the receiver's serial and the one sent with a push, ascending; key 4 (optional, only when there are any) holds signed certificates (§14.7) of short-lived keys that signed what the bundle carries or the push's attestation, their keys' and issuers' identities among the objects; a receiver keeps each that verifies with its issuer and refuses a bundle with one that does not |

| `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}`, and optionally, each only when there is one, `4: signed acceptance`, `5: log place`, `6: [cosigned checkpoint]`, meaning for the tag's attestation what a bookmark entry's keys 5 to 7 mean for its attestation (oxygen#129); a reader that does not know them ignores them |