Old clients are not sent tags only a certificate authorizes (closes #131) ee130dd9eef2

- **oxy 0.5.0 and older can clone a repository again after a keyless agent tagged it (#131).** Since #129 a release tag may be signed by a ten-minute certified key, which released clients do not know how to authorize: they refused the tag (`key … may not create tags/v0.5.0 under this repository's policy`), and with it the whole clone, fetch or `oxy submodule update`. Clients now send `User-Agent: oxy/<version>` and declare what they understand in `Oxy-Features` (`certified-tags` so far; docs/protocol.md, *Client capabilities*). Under a policy, a server leaves out of its refs answer to a client that does not declare `certified-tags` every tag that only a certificate authorizes, so that client clones the rest as if the tag did not exist. The rule is `Repo::refs_for_client` in oxy-core; `oxy-server` gains a `Backend::adjust_refs` hook, given the request headers, whose default applies it, so `oxy serve` and every embedding host do.

/// The request header in which a client declares the protocol features it

/// understands beyond the 0.5.0-era set: a comma-separated list, which a

/// server may tailor its answers to (docs/protocol.md, *Client

/// capabilities*). A request without it is a client of that era.

pub const FEATURES_HEADER: &str = "Oxy-Features";

/// The feature of a client that authorizes a tag signed by a short-lived,

/// certified key by its certificate at the time the host accepted it

/// (oxygen#129). A client without it refuses such a tag, and with it the

/// whole fetch, so servers leave those tags out of its `refs` (oxygen#131).

pub const FEATURE_CERTIFIED_TAGS: &str = "certified-tags";

/// The features this client declares in [`FEATURES_HEADER`].

pub const CLIENT_FEATURES: &[&str] = &[FEATURE_CERTIFIED_TAGS];

/// The `User-Agent` every request of this client sends: `oxy/<version>`.

pub fn user_agent() -> String {

    format!("oxy/{}", env!("CARGO_PKG_VERSION"))

}

/// Whether a [`FEATURES_HEADER`] value (absent: `None`) declares `feature`.

/// Entries are comma-separated, compared without surrounding blanks and

/// regardless of case; unknown ones are ignored.

pub fn declares_feature(header: Option<&str>, feature: &str) -> bool {

    header.is_some_and(|h| h.split(',').any(|f| f.trim().eq_ignore_ascii_case(feature)))

}

            .user_agent(&user_agent())

        req = req

            .set("Accept", CONTENT_TYPE)

            .set(FEATURES_HEADER, &CLIENT_FEATURES.join(","));

        .user_agent(&user_agent())

        .user_agent(&user_agent())

    #[test]

    fn client_features_are_declared_and_read() {

        assert_eq!(CLIENT_FEATURES.join(","), "certified-tags");

        assert!(user_agent().starts_with("oxy/"));

        assert!(declares_feature(

            Some("certified-tags"),

            FEATURE_CERTIFIED_TAGS

        ));

        assert!(declares_feature(

            Some("later-thing, Certified-Tags ,x"),

            FEATURE_CERTIFIED_TAGS

        ));

        assert!(!declares_feature(

            Some("certified-tags-v2"),

            FEATURE_CERTIFIED_TAGS

        ));

        assert!(!declares_feature(Some(""), FEATURE_CERTIFIED_TAGS));

        assert!(!declares_feature(None, FEATURE_CERTIFIED_TAGS));

    }

    /// Whether policy `p` authorizes the signer of tag `name`'s attestation

    /// `sa` without a certificate: a key its rule lists, a delegate of one,

    /// or a key one of them was rotated from (spec §14.5, §14.2). These are

    /// the only ways a client before oxygen#129 authorizes a tag.

    fn tag_signer_listed(&self, p: &crate::policy::Policy, name: &str, sa: &SignedAttest) -> bool {

        let Some(sig) = sa.sigs.first() else {

            return false;

        };

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

        let at = sa.attest.hlc.wall_ms;

        p.authorizes(&sig.key, &reference)

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

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

    }

    /// Tailor a `refs` answer of this repository to a client that declared

    /// `features` (the [`FEATURES_HEADER`] value; `None` when it sent none).

    /// A client without [`FEATURE_CERTIFIED_TAGS`] (oxy 0.5.0 and older)

    /// refuses a tag signed by a short-lived key that only its certificate

    /// authorizes, and with it the whole clone or fetch (oxygen#131), so

    /// under a policy each tag whose signer the policy does not list, as a

    /// key, a delegate or a rotation predecessor, is left out: that client

    /// sees the repository as if the tag did not exist. A tag with no

    /// signed attestation is left as it is (every client refuses it alike),

    /// as is everything without a policy.

    ///

    /// [`FEATURES_HEADER`]: crate::protocol::FEATURES_HEADER

    /// [`FEATURE_CERTIFIED_TAGS`]: crate::protocol::FEATURE_CERTIFIED_TAGS

    pub fn refs_for_client(

        &self,

        refs: &mut crate::protocol::RefsResponse,

        features: Option<&str>,

    ) {

        if crate::protocol::declares_feature(features, crate::protocol::FEATURE_CERTIFIED_TAGS) {

            return;

        }

        let Some(sp) = refs.policy.as_ref() else {

            return;

        };

        refs.tags.retain(|t| match &t.attestation {

            Some(sa) if !sa.sigs.is_empty() => self.tag_signer_listed(&sp.policy, &t.name, sa),

            _ => true,

        });

    }

                let listed = self.tag_signer_listed(p, &t.name, sa);

    // Without a policy every client is sent every tag, whatever features

    // it declares (oxygen#131).

    let mut refs = a.remote_refs().unwrap();

    a.refs_for_client(&mut refs, None);

    assert_eq!(refs.tags.len(), 1);

    /// Tailor a refs answer to the client asking, by its request headers

    /// (its `User-Agent` and the features it declares in `Oxy-Features`),

    /// after [`Backend::add_log`]. The default leaves out the tags a client

    /// that does not declare `certified-tags` would refuse

    /// ([`Repo::refs_for_client`], oxygen#131); a host that overrides it

    /// should apply that too ([`tailor_refs`]).

    fn adjust_refs(

        &self,

        _name: &str,

        repo: &Repo,

        refs: &mut oxy_core::protocol::RefsResponse,

        headers: &HeaderMap,

    ) {

        tailor_refs(repo, refs, headers);

    }

                self.backend.adjust_refs(name, &r, &mut refs, headers);

}

/// The features a request declares in its `Oxy-Features` header, as the

/// header's text; `None` when it sent none (a client of the 0.5.0 era).

pub fn client_features(headers: &HeaderMap) -> Option<&str> {

    headers

        .get(oxy_core::protocol::FEATURES_HEADER)

        .and_then(|v| v.to_str().ok())

}

/// Tailor `refs` of `repo` to the client whose request carried `headers`:

/// the shared rule of [`Repo::refs_for_client`], which every host applies.

pub fn tailor_refs(repo: &Repo, refs: &mut oxy_core::protocol::RefsResponse, headers: &HeaderMap) {

    repo.refs_for_client(refs, client_features(headers));

/// oxygen#131: oxy 0.5.0 and older authorize a tag only by a key the

/// policy lists (or its delegate or predecessor) and fail the whole clone

/// on any other, so a client that does not declare `certified-tags` is

/// never sent a tag that only a short-lived key's certificate authorizes.

/// It clones the rest without error; a current client still gets the tag;

/// and an old client that holds such a tag pushes without trouble.

#[test]

fn a_client_without_certified_tags_never_sees_a_tag_only_a_certificate_authorizes() {

    use axum::extract::{Path as AxPath, State};

    use axum::http::{HeaderMap, Method, StatusCode};

    use axum::response::{IntoResponse, Response};

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

    use oxy_core::identity::{Identity, Scope, SecretKey};

    use oxy_core::protocol::{wire, RemoteOptions, FEATURES_HEADER};

    use oxy_core::repo::IdentityScope;

    use oxy_server::{Access, Backend, Endpoint, Failure, Server};

    use std::sync::Arc;

    // A host that countersigns when it accepted a certified key's tag, as

    // a hub does.

    struct Host {

        root: std::path::PathBuf,

        acceptor: (Identity, SecretKey),

    }

    impl Backend for Host {

        fn open(&self, name: &str) -> Result<Repo, Failure> {

            Repo::open(&self.root.join(name))

                .map(|r| r.with_acceptor(self.acceptor.0.clone(), self.acceptor.1.clone()))

                .map_err(|e| Failure(StatusCode::NOT_FOUND, e.to_string()))

        }

        fn authorize(&self, _: &str, _: Access, _: &HeaderMap) -> Result<(), Failure> {

            Ok(())

        }

    }

    // `/new/...` as clients send it; `/old/...` without the features

    // header, as oxy 0.5.0 sends it.

    async fn route(

        State(server): State<Arc<Server>>,

        AxPath((era, repo, endpoint)): AxPath<(String, String, String)>,

        method: Method,

        mut headers: HeaderMap,

        body: axum::body::Bytes,

    ) -> Response {

        if era == "old" {

            headers.remove(FEATURES_HEADER);

        }

        match Endpoint::parse(&endpoint) {

            Some(e) => server.handle(repo, e, &method, &headers, body).await,

            None => Failure(StatusCode::NOT_FOUND, "no such endpoint".into()).into_response(),

        }

    }

    hermetic();

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

    let root = dir.path();

    let served = root.join("served");

    Repo::init(&served.join("origin")).unwrap();

    let hub_sk = SecretKey::generate();

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

    let server = Server::new(Host {

        root: served.clone(),

        acceptor: (hub.clone(), hub_sk.clone()),

    });

    let listener = TcpListener::bind("127.0.0.1:0").unwrap();

    let port = listener.local_addr().unwrap().port();

    std::thread::spawn(move || {

        let rt = tokio::runtime::Builder::new_multi_thread()

            .enable_all()

            .build()

            .unwrap();

        rt.block_on(async move {

            listener.set_nonblocking(true).unwrap();

            let app = axum::Router::new()

                .route("/{era}/{repo}/oxy/v1/{endpoint}", axum::routing::any(route))

                .with_state(server);

            axum::serve(tokio::net::TcpListener::from_std(listener).unwrap(), app)

                .await

                .unwrap();

        });

    });

    std::thread::sleep(std::time::Duration::from_millis(50));

    let new_url = format!("http://127.0.0.1:{port}/new/origin");

    let old_url = format!("http://127.0.0.1:{port}/old/origin");

    // Ada's policy grants the hub's certified agents; her own tag v0 is

    // by a key the policy lists.

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

    a.policy_grant_subject(

        "agent:claude@ada",

        hub.clone(),

        Scope::CHANGES | Scope::REFS,

        Some("*"),

    )

    .unwrap();

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

    a.tag_create("v0", &heads, "zero").unwrap();

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

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

    // A keyless agent's tag v1, by a key the hub certified for ten minutes.

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

    let mut c = Repo::clone(&new_url, &root.join("claude"))

        .unwrap()

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

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

    let (_, id) = c

        .create_identity("claude", "[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: now - 60_000,

            expires: now + 600_000,

            grant: None,

        },

        &hub,

        &hub_sk,

    );

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

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

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

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

    // The refs answer: without the header, v1 is left out; with it, there.

    let tags = |bytes: Vec<u8>| -> Vec<String> {

        let (_, refs) = wire::decode_refs(&bytes).unwrap();

        refs.tags.into_iter().map(|t| t.name).collect()

    };

    let bare =

        oxy_core::protocol::http_get(&format!("{new_url}/oxy/v1/refs"), &RemoteOptions::default())

            .unwrap();

    assert_eq!(tags(bare), ["v0"], "no Oxy-Features header");

    let remote = oxy_core::protocol::open_remote(&new_url, &RemoteOptions::default()).unwrap();

    let mut current: Vec<String> = remote

        .refs()

        .unwrap()

        .tags

        .into_iter()

        .map(|t| t.name)

        .collect();

    current.sort();

    assert_eq!(

        current,

        ["v0", "v1"],

        "a current client declares certified-tags"

    );

    // An old-era client clones without error and sees no v1.

    let old = Repo::clone(&old_url, &root.join("old")).unwrap();

    assert_eq!(old.tag_heads("v0").unwrap(), Some(heads.clone()));

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

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

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

    // A current client adopts v1 by its certificate at the hub's acceptance.

    let b = Repo::clone(&new_url, &root.join("b")).unwrap();

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

    // A client holding v1 that pushes where v1 is hidden from it sends v1

    // again: the host already has it, so it is taken as it is, and the

    // bookmark moves.

    let r = a.fetch("origin").unwrap();

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

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

    a.config.set("remote.origin.url", &old_url).unwrap();

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

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

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

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

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

    // `oxy serve` applies the same rule.

    let base = start(&served, vec![]);

    let bare = oxy_core::protocol::http_get(

        &format!("{base}/origin/oxy/v1/refs"),

        &RemoteOptions::default(),

    )

    .unwrap();

    assert_eq!(tags(bare), ["v0"], "oxy serve, no header");

    let remote =

        oxy_core::protocol::open_remote(&format!("{base}/origin"), &RemoteOptions::default())

            .unwrap();

    assert_eq!(

        remote.refs().unwrap().tags.len(),

        2,

        "oxy serve, current client"

    );

}

Client capabilities: the reference client sends `User-Agent:

oxy/<version>` and `Oxy-Features: <feature>[,<feature>…]` on every request,

a comma-separated list (blanks around entries and case are ignored, unknown

entries too) of what it understands beyond the oxy 0.5.0 feature set.

Servers may tailor their answers to the features a request declares, and a

request without the header is a client of that era. Features so far:

- `certified-tags`: the client authorizes a tag signed by a short-lived,

  certified key by a subject grant, its certificate checked at the time

  the host accepted the tag (spec §14.7; oxygen#129). A client without it

  authorizes a tag only by a key the policy's rule lists, a delegate of one

  or a rotation predecessor, and fails the whole clone or fetch on any

  other. So under a policy, a server leaves out of a `refs` answer to such

  a client every tag whose attestation's signer none of those authorizes

  (`Repo::refs_for_client`, applied by `oxy serve` and by default by every

  `oxy_server` host): that client sees the repository as if those tags did

  not exist. If it holds one of them already and pushes, it sends the tag

  again (it is not in the answer); the server already has it in the same

  state and takes it as it is.

`after_push` hook, `adjust_refs`, which tailors a refs answer to the

request's headers and by default applies the rule above, and `vet_push`, with which a host refuses a push by