Create and withdraw tags on the website (closes #295, closes #301) ba0a55bb5b3c

//! Making and withdrawing tags for a signed-in user (#295, #301), from the

//! Tags page and the API: signed by the hub key as the user's delegate (in a

//! repository without a trust policy, by the hub's own key when the user has

//! not delegated), received as a pushed tag or withdrawal is, so the same

//! checks apply, then recorded, audited and logged as a push would be.

use crate::db::{self, accounts::Account};

use crate::repos::edits::Signer;

use crate::repos::RepoName;

use crate::Shared;

use oxy_core::hash::ChangeHash;

/// A tag made or withdrawn.

pub struct Done {

    pub name: String,

    /// The state it names (hex).

    pub state: String,

    pub heads: Vec<ChangeHash>,

}

/// Who may sign for the user: the hub key as their delegate, else (only

/// where no trust policy asks for the user) the hub's own key.

struct Signers {

    delegate: Option<Signer>,

    hub: Option<Signer>,

    /// Why there is no delegate.

    why: String,

}

impl Signers {

    async fn of(app: &Shared, me: &Account) -> Signers {

        match crate::web::edit::signer_for(app, me.id).await {

            Ok(s) => Signers { delegate: Some(s), hub: None, why: String::new() },

            Err(why) => Signers { delegate: None, hub: crate::web::edit::hub_signer(app).ok(), why },

        }

    }

    fn pick(self, policy: bool) -> Result<Signer, String> {

        match (self.delegate, self.hub) {

            (Some(s), _) => Ok(s),

            (None, Some(h)) if !policy => Ok(h),

            _ => Err(self.why),

        }

    }

}

/// Create tag `name` for the state of `target` (a bookmark, tag or change;

/// the default bookmark when empty).

pub async fn create(

    app: &Shared,

    row: &db::repos::RepoRow,

    repo: &RepoName,

    me: &Account,

    name: &str,

    target: &str,

    message: &str,

) -> Result<Done, String> {

    let name = name.trim().to_string();

    if name.is_empty() {

        return Err("A tag needs a name.".into());

    }

    let target = match target.trim() {

        "" => row.default_bookmark.clone(),

        t => t.to_string(),

    };

    let signers = Signers::of(app, me).await;

    let (n, msg, rid) = (name.clone(), message.trim().to_string(), row.id);

    let out = app

        .repos

        .write(repo, move |r, _| {

            if r.tag_heads(&n)?.is_some() {

                return Ok(Err(format!("There is already a tag {n}, and tags are immutable: withdraw it and tag under a new name.")));

            }

            let Ok(heads) = r.resolve_heads(&target) else {

                return Ok(Err(format!("There is no bookmark, tag or change {target}.")));

            };

            let signer = match signers.pick(r.current_policy()?.is_some()) {

                Ok(s) => s,

                Err(why) => return Ok(Err(why)),

            };

            let report = r.host_tag_create(

                &n,

                &heads,

                &msg,

                (&signer.hub_key, &signer.hub_secret),

                &[signer.hub_identity.clone(), signer.author.clone()],

            )?;

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

            match report.results.iter().find(|x| x.name == reference) {

                Some(x) if x.ok => {}

                Some(x) => return Ok(Err(x.reason.clone())),

                None => return Ok(Err("the repository took nothing".into())),

            }

            let state = r.view()?.tags.get(&n).map(|s| s.to_hex()).unwrap_or_default();

            let heads = r.tag_heads(&n)?.unwrap_or_default();

            Ok(Ok((state, heads, crate::tlog::push_entries(r, Some(rid), &report))))

        })

        .await

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

    let (state, heads, entries) = out?;

    crate::tlog::log(app, entries).await;

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

    let outcome = db::repos::PushOutcome {

        reference: reference.clone(),

        ok: true,

        reason: "tagged on the hub".into(),

        old_state: String::new(),

        new_state: state.clone(),

        heads: heads.len() as i64,

        changes: 0,

    };

    db::repos::record_push(&app.db, row.id, Some((me.id, &me.username)), &[outcome]).await.ok();

    db::accounts::audit(&app.db, Some(me), "tag.created", &format!("{}/{}", row.owner, row.name), &name).await.ok();

    crate::hooks::emit(

        app,

        row,

        "push",

        &me.username,

        serde_json::json!({ "updates": [{ "reference": reference, "old_state": "", "new_state": state, "heads": heads.len(), "changes": 0 }], "via": "web" }),

    )

    .await;

    // A tag runs the jobs whose `on` names it, as a pushed one does.

    crate::flow::on_push(app, row, &reference, &state, &heads, &me.username).await;

    Ok(Done { name, state, heads })

}

/// Withdraw tag `tag`, saying why. Refused while a release uses it.

pub async fn withdraw(

    app: &Shared,

    row: &db::repos::RepoRow,

    repo: &RepoName,

    me: &Account,

    tag: &str,

    reason: &str,

) -> Result<Done, String> {

    let tag = tag.trim().to_string();

    if let Ok(Some(rel)) = db::releases::get(&app.db, row.id, &tag).await {

        return Err(format!("The release {:?} uses {tag}: delete the release first.", rel.title));

    }

    let signers = Signers::of(app, me).await;

    let (t, why, rid) = (tag.clone(), reason.trim().to_string(), row.id);

    let out = app

        .repos

        .write(repo, move |r, _| {

            let Some(state) = r.view()?.tags.get(&t).copied() else {

                return Ok(Err(format!("There is no tag {t}.")));

            };

            let heads = r.store().get_state(&state).map(|s| s.heads).unwrap_or_default();

            let signer = match signers.pick(r.current_policy()?.is_some()) {

                Ok(s) => s,

                Err(why) => return Ok(Err(why)),

            };

            let report = r.host_tag_withdrawal(

                &t,

                &why,

                (&signer.hub_key, &signer.hub_secret),

                &[signer.hub_identity.clone(), signer.author.clone()],

            )?;

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

            match report.results.iter().find(|x| x.name == reference) {

                Some(x) if x.ok => {}

                Some(x) => return Ok(Err(x.reason.clone())),

                None => return Ok(Err("the repository took nothing".into())),

            }

            Ok(Ok((state.to_hex(), heads, crate::tlog::push_entries(r, Some(rid), &report))))

        })

        .await

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

    let (state, heads, entries) = out?;

    crate::tlog::log(app, entries).await;

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

    let outcome = db::repos::PushOutcome {

        reference: reference.clone(),

        ok: true,

        reason: if reason.trim().is_empty() { "withdrawn on the hub".into() } else { format!("withdrawn on the hub: {}", reason.trim()) },

        old_state: state.clone(),

        new_state: oxy_core::hash::ObjectRef::ZERO.to_hex(),

        heads: 0,

        changes: 0,

    };

    db::repos::record_push(&app.db, row.id, Some((me.id, &me.username)), &[outcome]).await.ok();

    db::accounts::audit(

        &app.db,

        Some(me),

        "tag.withdrawn",

        &format!("{}/{}", row.owner, row.name),

        format!("{tag} {}", reason.trim()).trim_end(),

    )

    .await

    .ok();

    crate::hooks::emit(

        app,

        row,

        "push",

        &me.username,

        serde_json::json!({ "updates": [{ "reference": reference, "old_state": state, "new_state": oxy_core::hash::ObjectRef::ZERO.to_hex(), "heads": 0, "changes": 0, "deleted": true }], "via": "web" }),

    )

    .await;

    Ok(Done { name: tag, state, heads })

}

- **Create and withdraw tags on the website (#295, #301):** a writer creates a tag on the Tags page (or `oh tag create`, `POST …/tags`), signed by the hub as their delegate, under the policy, and its tag jobs run; a maintainer withdraws one there (or `oh tag delete`, `DELETE …/tags/{tag}`, or `oxy push --delete tags/NAME`) with a signed withdrawal, never while a release uses it. The withdrawal is logged, audited and listed on the page with why, and clones drop the tag on their next fetch. Tags never move, and a withdrawn name is not used again. Pins oxygen with tag withdrawal and with keyless grants that survive their owner's key rotation (oxygen#135).

/// `POST …/tags` (#295): tag the state of `target` (a bookmark, tag or

/// change; the default bookmark when absent).

pub struct NewTag {

    pub name: String,

    #[serde(default)]

    pub target: Option<String>,

    #[serde(default)]

    pub message: Option<String>,

}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

        .route("/repos/{owner}/{name}/tags", get(tags).post(create_tag))

        .route("/repos/{owner}/{name}/tags/{tag}", axum::routing::delete(withdraw_tag))

/// `POST …/tags` (#295): what the Tags page's Create does.

async fn create_tag(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name)): Path<(String, String)>,

    Json(body): Json<NewTag>,

) -> Result<(StatusCode, Json<Tag>), ApiError> {

    let c = caller(&app, &headers).await?;

    let me = c.require("repo:write")?.clone();

    let (repo, row, _) = reach(&app, &c, &owner, &name, Access::Write).await?;

    let made = crate::tags::create(

        &app,

        &row,

        &repo,

        &me,

        &body.name,

        body.target.as_deref().unwrap_or(""),

        body.message.as_deref().unwrap_or(""),

    )

    .await

    .map_err(|m| ApiError(StatusCode::BAD_REQUEST, m))?;

    let t = app

        .repos

        .read(&repo, |r, _| view::tags(r))

        .await?

        .into_iter()

        .find(|t| t.name == made.name)

        .ok_or_else(|| not_found("no such tag"))?;

    Ok((StatusCode::CREATED, Json(Tag { name: t.name, heads: t.heads, message: t.message, signer: t.signer })))

}

#[derive(Deserialize)]

struct WithdrawQuery {

    #[serde(default)]

    reason: String,

}

/// `DELETE …/tags/{tag}?reason=…` (#301): what the Tags page's Withdraw

/// does. Maintainers; refused (409) while a release uses the tag.

async fn withdraw_tag(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name, tag)): Path<(String, String, String)>,

    Query(q): Query<WithdrawQuery>,

) -> Result<StatusCode, ApiError> {

    let c = caller(&app, &headers).await?;

    let me = c.require("repo:write")?.clone();

    let (repo, row, _) = reach(&app, &c, &owner, &name, Access::Maintain).await?;

    if db::releases::get(&app.db, row.id, &tag).await?.is_some() {

        return Err(ApiError(StatusCode::CONFLICT, format!("a release uses {tag}: delete the release first")));

    }

    crate::tags::withdraw(&app, &row, &repo, &me, &tag, &q.reason).await.map_err(|m| ApiError(StatusCode::BAD_REQUEST, m))?;

    Ok(StatusCode::NO_CONTENT)

}

pub mod tags;

    /// A tag a release names is not withdrawn (#301): the release would

    /// point at nothing. Delete the release first.

    fn vet_tag_withdrawal(&self, name: &str, tag: &str) -> Result<(), String> {

        let Some(parsed) = RepoName::parse(name) else { return Ok(()) };

        let Ok(row) = self.row(&parsed) else { return Ok(()) };

        match self.block(db::releases::get(&self.pool, row.id, tag)) {

            Ok(Some(rel)) => Err(format!("the release {:?} uses tags/{tag}: delete the release first", rel.title)),

            Ok(None) => Ok(()),

            Err(e) => Err(format!("could not check the releases of {name}: {e}")),

        }

    }

/// A tag withdrawn here (#301): the state it named, why, by whom and when.

pub struct WithdrawnView {

    pub name: String,

    pub heads: Vec<String>,

    pub reason: String,

    pub signer: Option<String>,

    pub when_ms: i64,

}

#[derive(Clone, Debug)]

    Ok(out)

}

/// The tags withdrawn here, newest first.

pub fn withdrawn_tags(repo: &Repo) -> Result<Vec<WithdrawnView>> {

    let mut out: Vec<WithdrawnView> = repo

        .remote_refs()?

        .withdrawn

        .into_iter()

        .filter_map(|t| {

            let sa = t.attestation?;

            let oxy_core::attest::AttestBody::Untag { reason, .. } = &sa.attest.body else { return None };

            Some(WithdrawnView {

                name: t.name,

                heads: t.heads.iter().map(|h| h.to_hex()).collect(),

                reason: reason.clone(),

                signer: sa.sigs.first().and_then(|s| repo.store().get_identity(&s.key).ok()).map(|i| i.name),

                when_ms: sa.attest.hlc.wall_ms as i64,

            })

        })

        .collect();

    out.sort_by_key(|w| std::cmp::Reverse(w.when_ms));

        if !report.results.iter().any(|r| r.ok && r.name == u.name) {

        // A tag's withdrawal (#301), and when the hub accepted it.

        if let (Some(tag), true) = (u.name.strip_prefix("tags/"), u.new_state.is_zero()) {

            if let Ok(Some((r, sa))) = repo.tag_withdrawal(tag) {

                add(&mut out, "untag", r, sig_keys(&sa.sigs));

                if let Ok(Some(acc)) = repo.acceptance_of(&r) {

                    add(&mut out, "accepted", acc.attest.hash(), sig_keys(&acc.sigs));

                }

            }

            continue;

        }

        if u.new_state.is_zero() {

            continue;

        }

        .route("/{owner}/{name}/tags/create", post(refs::create_tag))

        .route("/{owner}/{name}/tags/withdraw", post(refs::withdraw_tag))

    withdrawn: Vec<view::WithdrawnView>,

    /// Tags a release uses (not withdrawn while it does).

    released: Vec<String>,

    can_create: bool,

    can_withdraw: bool,

    notice: Option<String>,

    error: Option<String>,

impl TagsPage {

    fn released(&self, tag: &str) -> bool {

        self.released.iter().any(|t| t == tag)

    }

}

async fn tags_page(

    app: &Shared,

    shell: Shell,

    repo: crate::repos::RepoName,

    row: db::repos::RepoRow,

    role: Role,

    notice: Option<String>,

    error: Option<String>,

) -> Result<Page<TagsPage>, Error> {

    let (tags, withdrawn) = app

        .repos

        .read(&repo, |r, _| Ok((view::tags(r)?, view::withdrawn_tags(r)?)))

        .await

        .map_err(|e| Error::from_repo(shell.clone(), e))?;

    let released = db::releases::list(&app.db, row.id).await.unwrap_or_default().into_iter().map(|r| r.tag).collect();

    let signed_in = shell.user.is_some();

    Ok(Page(TagsPage {

        shell,

        repo: RepoShell::new(app, &row, "tags").with_role(role),

        tags,

        withdrawn,

        released,

        can_create: signed_in && role >= Role::Write,

        can_withdraw: signed_in && role >= Role::Maintain,

        notice,

        error,

    }))

}

    tags_page(&app, shell, repo, row, role, None, None).await

}

#[derive(Deserialize)]

pub struct CreateTagForm {

    #[serde(rename = "_csrf")]

    csrf_token: String,

    name: String,

    #[serde(default)]

    target: String,

    #[serde(default)]

    message: String,

}

/// Create a tag from the web (#295): signed by the hub key as the user's

/// delegate, under the policy, as `oxy tag create` and a push would be.

pub async fn create_tag(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name)): Path<(String, String)>,

    Form(f): Form<CreateTagForm>,

) -> Result<Page<TagsPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/tags"), &viewer);

    let me = require(&viewer, &shell)?;

    let (repo, row, role) = lookup_role(&app, &shell, &viewer, &owner, &name, Access::Write).await?;

    csrf(&viewer, &f.csrf_token, &shell)?;

    match crate::tags::create(&app, &row, &repo, &me.account, &f.name, &f.target, &f.message).await {

        Ok(t) => {

            let notice = format!(

                "Tagged {} ({} head{}). Start a release from it under Releases.",

                t.name,

                t.heads.len(),

                if t.heads.len() == 1 { "" } else { "s" }

            );

            tags_page(&app, shell, repo, row, role, Some(notice), None).await

        }

        Err(e) => tags_page(&app, shell, repo, row, role, None, Some(format!("Could not create the tag: {e}"))).await,

    }

}

#[derive(Deserialize)]

pub struct WithdrawTagForm {

    #[serde(rename = "_csrf")]

    csrf_token: String,

    tag: String,

    #[serde(default)]

    reason: String,

}

/// Withdraw a tag from the web (#301), as `oxy push --delete tags/NAME`

/// does: a signed withdrawal, kept and logged. Maintainers only; never

/// while a release uses the tag.

pub async fn withdraw_tag(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name)): Path<(String, String)>,

    Form(f): Form<WithdrawTagForm>,

) -> Result<Page<TagsPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/tags"), &viewer);

    let me = require(&viewer, &shell)?;

    let (repo, row, role) = lookup_role(&app, &shell, &viewer, &owner, &name, Access::Maintain).await?;

    csrf(&viewer, &f.csrf_token, &shell)?;

    match crate::tags::withdraw(&app, &row, &repo, &me.account, &f.tag, &f.reason).await {

        Ok(t) => {

            let notice = format!("Withdrew {}. Clones drop it on their next fetch; the name is not used again.", t.name);

            tags_page(&app, shell, repo, row, role, Some(notice), None).await

        }

        Err(e) => tags_page(&app, shell, repo, row, role, None, Some(format!("Could not withdraw {}: {e}", f.tag.trim()))).await,

    }

/// #295, #301: a tag is made on the hub (signed by its key as the user's

/// delegate, or its own key where no policy asks for the user), and

/// withdrawn there or by a push, never while a release uses it; a clone

/// drops it on its next fetch, and the withdrawal is audited and logged.

#[tokio::test(flavor = "multi_thread")]

async fn tags_are_made_and_withdrawn_on_the_hub() {

    hermetic();

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

    let mut config = Config::load(dir.path()).unwrap();

    config.registration.setup_code = "test-setup".into();

    config.auth.push_tokens = vec!["site".into()];

    config.registration.mode = "open".into();

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

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

    config.server.base_url = format!("http://127.0.0.1:{port}");

    let app = oxygenhub::build(config).await.unwrap();

    let router = oxygenhub::router(app.clone());

    tokio::spawn(async move { axum::serve(listener, router).await.unwrap() });

    let base = format!("http://127.0.0.1:{port}");

    let app = &app;

    let andy = send(

        app,

        "POST",

        "/register",

        None,

        None,

        Some("application/x-www-form-urlencoded"),

        b"username=andy&email=a%40example.com&password=correct-horse-battery&setup=test-setup".to_vec(),

    )

    .await

    .cookie

    .unwrap();

    let andy_id = db::accounts::account_by_name(&app.db, "andy").await.unwrap().unwrap().id;

    let repo = RepoName::parse("andy/demo").unwrap();

    app.repos.create(&repo, None).unwrap();

    db::repos::create(&app.db, "andy", "demo", "", hub_api::Visibility::Public).await.unwrap();

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

    let mut client = Repo::init(work.path()).unwrap();

    client.create_identity("Andy", "[email protected]", IdentityScope::Repo).unwrap();

    client.config.set("core.sign", "change").unwrap();

    client.config.set("remote.origin.url", &format!("{base}/andy/demo")).unwrap();

    client.config.set("remote.origin.token", "site").unwrap();

    client.save_config().unwrap();

    write(work.path(), "a.txt", b"one\n");

    client.snapshot("t").unwrap();

    let c1 = client.commit("First", &[]).unwrap();

    client.tag_create("v0.1", &[c1], "").unwrap();

    client.tag_create("v0.2", &[c1], "").unwrap();

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

    let host = || app.repos.open(&repo).unwrap();

    let page = send(app, "GET", "/andy/demo/tags", Some(&andy), None, None, vec![]).await.text();

    assert!(page.contains("Create a tag") && page.contains("WITHDRAW"), "{page}");

    let csrf = csrf_of(&page);

    // Not delegated, no policy: the hub's own key signs it.

    let r = form(app, "/andy/demo/tags/create", &andy, &format!("_csrf={csrf}&name=v0.3&target=main&message=Third")).await;

    assert!(r.text().contains("Tagged v0.3"), "{}", r.text());

    assert_eq!(host().tag_heads("v0.3").unwrap(), Some(vec![c1]));

    // Delegated: as Andy's delegate.

    client.delegate_add(app.hub_key.identity.clone(), oxy_core::identity::Scope::CHANGES | oxy_core::identity::Scope::REFS, None).unwrap();

    let key = client.config.author_key.unwrap();

    let id = client.identity(&key).unwrap();

    db::accounts::link_identity(&app.db, andy_id, &key.to_hex(), &id.name, &id.email, &id.encode()).await.unwrap();

    let r = form(app, "/andy/demo/tags/create", &andy, &format!("_csrf={csrf}&name=v0.4&message=Fourth")).await;

    assert!(r.text().contains("Tagged v0.4"), "{}", r.text());

    let t = host().tags().unwrap().into_iter().find(|t| t.name == "v0.4").unwrap();

    assert!(t.signer.is_some(), "signed by the hub key for Andy");

    let r = form(app, "/andy/demo/tags/create", &andy, &format!("_csrf={csrf}&name=v0.4")).await;

    assert!(r.text().contains("immutable"), "a tag never moves: {}", r.text());

    // The clone takes the hub's tags.

    assert_eq!(client.fetch("origin").unwrap().new_tags, 2);

    assert!(client.tag_heads("v0.3").unwrap().is_some());

    // A release on v0.1: neither the page nor a push withdraws it.

    db::releases::create(&app.db, db::repos::get(&app.db, "andy", "demo").await.unwrap().unwrap().id, "v0.1", "Zero one", "", false, None)

        .await

        .unwrap();

    let r = form(app, "/andy/demo/tags/withdraw", &andy, &format!("_csrf={csrf}&tag=v0.1")).await;

    assert!(r.text().contains("delete the release first"), "{}", r.text());

    let r = client.push_delete("origin", "tags/v0.1").unwrap();

    assert!(!r[0].ok && r[0].reason.contains("delete the release first"), "{r:?}");

    assert!(host().tag_heads("v0.1").unwrap().is_some());

    // On the page: gone, listed as withdrawn with why, and audited.

    let r = form(app, "/andy/demo/tags/withdraw", &andy, &format!("_csrf={csrf}&tag=v0.3&reason=tagged+by+mistake")).await;

    assert!(r.text().contains("Withdrew v0.3"), "{}", r.text());

    assert_eq!(host().tag_heads("v0.3").unwrap(), None);

    let page = send(app, "GET", "/andy/demo/tags", Some(&andy), None, None, vec![]).await.text();

    assert!(page.contains("Withdrawn") && page.contains("tagged by mistake"), "{page}");

    let (w, _) = host().tag_withdrawal("v0.3").unwrap().unwrap();

    assert!(db::tlog::entry_of(&app.db, &w.to_hex(), "untag").await.unwrap().is_some(), "logged");

    let audited: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM audit WHERE action = 'tag.withdrawn'").fetch_one(&app.db).await.unwrap();

    assert_eq!(audited, 1);

    // A clone drops it on its next fetch.

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

    assert_eq!(rep.withdrawn_tags, vec!["v0.3".to_string()]);

    assert_eq!(client.tag_heads("v0.3").unwrap(), None);

    // By a push: `oxy push --delete tags/NAME`.

    let r = client.push_delete("origin", "tags/v0.2").unwrap();

    assert!(r[0].ok, "{r:?}");

    assert_eq!(host().tag_heads("v0.2").unwrap(), None);

    let (w, _) = host().tag_withdrawal("v0.2").unwrap().unwrap();

    assert!(db::tlog::entry_of(&app.db, &w.to_hex(), "untag").await.unwrap().is_some(), "logged");

    // The name is never used again.

    let r = form(app, "/andy/demo/tags/create", &andy, &format!("_csrf={csrf}&name=v0.2")).await;

    assert!(r.text().contains("withdrawn"), "{}", r.text());

}

use hub_api::{FlowLogLine, FlowRun, Issue, IssueStateChange, NewComment, NewIssue, NewProposal, NewRelease, Proposal, Release, Tag};

    /// Tags: list, create, withdraw

    Tag {

        #[command(subcommand)]

        cmd: TagCmd,

    },

enum TagCmd {

    /// Tags, newest name first

    List,

    /// Tag the state of a bookmark, tag or change, signed by the hub as your

    /// delegate (as `oxy tag create` and a push would be)

    Create {

        name: String,

        /// What to tag (default: the default bookmark)

        #[arg(long)]

        target: Option<String>,

        #[arg(long, short)]

        message: Option<String>,

    },

    /// Withdraw a tag: a signed withdrawal, kept and logged; clones drop it on

    /// their next fetch, and the name is never used again. Refused while a

    /// release uses the tag

    Delete {

        name: String,

        /// Why, recorded with the withdrawal

        #[arg(long, short)]

        reason: Option<String>,

    },

}

#[derive(Subcommand)]

        Cmd::Tag { cmd } => tag(&c, &t, cmd, json),

        }

    }

    Ok(0)

}

fn tag(c: &Client, t: &Target, cmd: TagCmd, json: bool) -> Result<i32> {

    let base = t.repo_path()?;

    match cmd {

        TagCmd::List => {

            let path = format!("{base}/tags");

            if json {

                println!("{}", c.get_text(&path)?);

                return Ok(0);

            }

            let tags: Vec<Tag> = c.get(&path)?;

            if tags.is_empty() {

                println!("{}", ui::dim("no tags"));

            }

            for t in tags {

                let heads: Vec<&str> = t.heads.iter().map(|h| &h[..h.len().min(12)]).collect();

                let signer = t.signer.map(|s| format!("signed by {s}")).unwrap_or_else(|| "unsigned".into());

                println!("{}  {}  {}", t.name, ui::dim(&heads.join(" ")), ui::dim(&signer));

            }

        }

        TagCmd::Create { name, target, message } => {

            let new = hub_api::NewTag { name, target, message };

            let made: Tag = c.send("POST", &format!("{base}/tags"), &new)?;

            if json {

                println!("{}", serde_json::to_string(&made)?);

            } else {

                println!("{} tagged {} {}", ui::ok("✔"), made.name, ui::dim(&format!("{} head(s)", made.heads.len())));

            }

        }

        TagCmd::Delete { name, reason } => {

            let reason = reason.unwrap_or_default();

            c.send_text("DELETE", &format!("{base}/tags/{}?reason={}", enc(&name), enc(&reason)), &serde_json::json!({}))?;

            if json {

                println!("{}", serde_json::json!({ "withdrawn": name }));

            } else {

                println!("{} withdrew {} {}", ui::ok("✔"), name, ui::dim("(clones drop it on their next fetch)"));

            }

| `oh tag list`, `oh tag create NAME [--target REF] [-m MESSAGE]`, `oh tag delete NAME [-r REASON]` | Tags: made on the hub as your delegate; withdrawn with a signed withdrawal (never while a release uses one) |

Tags come from the repository (spec §10): a name, the state, and a signed attestation when the tagger signed. The tags page lists them with signature status. A writer creates one there (#295; `POST /tags`, `oh tag create NAME [--target REF] [-m MESSAGE]`): the hub signs it with its key as the user's delegate (in a repository without a trust policy, with its own key when the user has not delegated), and it is received as a pushed tag is, so the policy's rule for `tags/<name>` applies, the tag jobs of the pipeline run, and the push is recorded. Tags never move: a mistaken one is withdrawn (#301; Oxygen spec §10.2) by a maintainer there (`DELETE /tags/{tag}?reason=`, `oh tag delete NAME [-r REASON]`) or by `oxy push --delete tags/NAME`, with a signed `untag` attestation, never while a release uses the tag (delete the release first; a push's withdrawal is refused then too). The withdrawal is logged in the transparency log (`untag`), audited (`tag.withdrawn`) and recorded as a push; the page lists withdrawn tags with why, by whom and when, clones drop the tag on their next fetch, and the name is not used again. A release attaches to a tag: notes (Markdown, generated draft from the changes since the previous release), assets (uploaded files, content addressed, size limited by `asset_limit`), a pre-release flag, and a latest marker. Source archives (`.tar.zst`, `.zip`) of the tagged state are generated on demand and cached.

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses (an unknown route, or a known one with the wrong method, too), cursor pagination (`?after=`), ETags on cacheable resources, and rate limits per token. Resources mirror the pages: `/repos/{owner}/{name}`, `/bookmarks`, `/changes/{hash}`, `/tree/{ref}/{path}`, `/file/{ref}/{path}`, `/blame`, `/history/{ref}` (`?path=`, `?offset=&limit=`, or `?r=REVSET` for the changes a revset selects, evaluated under a two-second budget and answering 400 when it does not parse or goes past it; Oxygen's docs/revset_query_language.md), `/compare`, `/conflicts`, `/proposals` (`?state=open|draft|landed|closed|all`, open ones and drafts by default; a source bookmark may hold `/`, and `owner/name:bookmark` naming the repository itself is its own bookmark), `/proposals/{n}/comments|reviews|checks|files`, `PATCH /proposals/{n}` (the title and description, for its author or a maintainer, and `labels`, the whole set by name, for triage; what is not given stays), `POST /proposals/{n}/land` (repo:write: what the Land button does, `409` with the blockers when it cannot; a landed proposal keeps the changes it landed and reports `landed` with who, how (`web`, or `api (token NAME)`) and when, which its event, the audit log and the push record also say, adding when nobody approved), `/proposals/{n}/content/{base|head}/{path}` (a changed file's bytes in the target's state or the projected state, for editor diff views), `/issues` (creating an issue can set its labels, assignees and milestone; `PATCH /issues/{n}` edits the title and body for the author or triage, and replaces labels, assignees or the milestone for triage, recording each on the timeline; unknown names are refused before anything changes), `/labels` (`POST` creates or changes one, `DELETE /labels/{name}` removes it; triage), `/milestones` (`POST` creates one or changes the description and due date of the one with that title, `PATCH /milestones/{title}` changes title, description, due date or state; triage), `/releases` (`PATCH /releases/{tag}` changes the title, notes or prerelease flag, repo:write), `/tags` (`POST` creates one, repo:write; `DELETE /tags/{tag}` withdraws one, a maintainer, `409` while a release uses it; §9), `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/notifications` (the caller's inbox and unread count; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/users/{name}/drops` and `/drops` (§4.5), `/orgs/{name}`, `/checks/{state}` (the checks on a state, named by its hash, by its heads joined with `+`, by the one head of a single-head state, or by a bookmark), `/checks/required` (`GET`, and `PUT` of the whole list by a repository admin: the checks a proposal needs, passed, to land), `/projects/{owner}` (list, create) and `/projects/{owner}/{n}` (the board as the caller may see it, `PATCH` for title, description, privacy and closing, and `owner` to transfer it to an owner the caller may make boards under (#125: it takes the next number there, and its old address redirects), `/cards` to list them by column or add a reference or note to a column named by id or name, `/cards/{id}` to move or remove one; `repo:write` and the page's rights to change), `/coverage` and `/tests` (a bookmark's coverage and JUnit test reports from Flow jobs, newest first, `?bookmark=&limit=`), `POST /coverage` (repo:write, #136: `{"bookmark"}` or `{"change"}` and `content`, an LCOV or Cobertura report measured off the hub, kept for that state as uploaded by the caller, shown "uploaded by NAME" wherever a run number would be, and setting no check; `oh coverage upload FILE`), `/coverage/{id}` (a report with its files) and `/tests/{id}` (a report with its cases, `?status=failed` for the failed and errored ones), `/flow/runs` (`GET`: runs newest first, `?before=N&limit=`; `POST {"bookmark"}` or `{"change"}`, repo:write: run a bookmark's current state, the default bookmark when none is named, or one change's state; with `"jobs": [NAME..]` only those jobs and what they depend on, each one a manual run starts, else `409` naming the ones it does (#130); `oh run start --job NAME`), `/flow/runs/{n}` (a run with its jobs), `/flow/runs/{n}/jobs/{job}/log` (`?after=seq&limit=`) and `/flow/runs/{n}/rerun` (repo:write: a finished run again), both answering `201 {"number", "url"}` or `409` with why nothing started, `/flow/runs/{n}/jobs/{job}/rerun` (repo:write, oxygenflow#31: that job of a finished run again, in the same run, with the jobs that depend on it; what it depends on keeps its result, so a flaky test reruns without its build; their logs, artifacts and reports go, their checks return to queued and the run is running again; `{"queued": N}`, or `409` while the run is live or for a job it lacks; RE-RUN THIS JOB on the run page, `oh run rerun N --job NAME`), `/flow/runs/{n}/cancel` (repo:write: a run still going ends as `cancelled`, its running jobs stopped when their runner next reports; `409` when it had already ended; a push to a bookmark cancels the push runs of it still going), `/search`. A change's author carries the account its key is linked to, or `null` and a `note` saying the key is not linked and where its owner links it; `via` names the delegate (an agent) that signed for the author when one did, with the delegation's scope and expiry and whether it has since been revoked, and the pages show the same as an `agent` badge, a `via` row under the author on the change page, and a count under the author in Contributors (the change page shows a "key not linked" tag, with a link to Settings → Keys for signed-in viewers). Shapes reuse `oxy --json` shapes wherever one exists (change, status, blame, diff) so tools written against the CLI work against the hub. `crates/hub-api` holds the types with `serde` derives and is what the runner and the VS Code extension will link.

{% if let Some(n) = notice %}<p class="note">{{ n }}</p>{% endif %}

{% if let Some(e) = error %}<p class="error">{{ e }}</p>{% endif %}

{% if can_create %}

<details class="tag-create"{% if error.is_some() %} open{% endif %}><summary>Create a tag</summary>

  <form class="card wide" method="post" action="{{ repo.url }}/tags/create">

    <input type="hidden" name="_csrf" value="{{ shell.csrf }}">

    <label for="tag-name">Name</label><input type="text" id="tag-name" name="name" placeholder="v1.0.0" required>

    <label for="tag-target">Of</label><input type="text" id="tag-target" name="target" placeholder="{{ repo.default_bookmark }}">

    <label for="tag-message">Message</label><input type="text" id="tag-message" name="message">

    <p class="small mute">Signed by this hub's key as your delegate, as <code>oxy tag create</code> and a push would be. Tags never move; a mistake is withdrawn, and its name is not used again.</p>

    <div class="choice"><button type="submit">CREATE TAG</button></div>

  </form>

</details>

{% endif %}

{% if tags.is_empty() %}<p class="empty">No tags. <code>oxy tag create NAME -m "message"</code> then push{% if can_create %}, or create one above{% endif %}.</p>{% else %}

<tr><th>Tag</th><th>State</th><th>Message</th><th>Signed</th>{% if can_withdraw %}<th></th>{% endif %}</tr>

  {% if can_withdraw %}<td class="small">{% if self.released(t.name.as_str()) %}<span class="mute" title="Delete the release first">in a release</span>{% else %}

    <details class="tiny"><summary>withdraw</summary><form class="tiny" method="post" action="{{ repo.url }}/tags/withdraw"><input type="hidden" name="_csrf" value="{{ shell.csrf }}"><input type="hidden" name="tag" value="{{ t.name }}"><input type="text" name="reason" placeholder="why (optional)" aria-label="Why {{ t.name }} is withdrawn"> <button type="submit" class="small danger-btn" data-confirm="Withdraw the tag {{ t.name }}? Clones drop it on their next fetch, and the name can never be used again.">WITHDRAW</button></form></details>{% endif %}</td>{% endif %}

</tr>

{% endfor %}

</table></div>

{% endif %}

{% if !withdrawn.is_empty() %}

<h2>Withdrawn <small>{{ withdrawn.len() }}</small></h2>

<div class="table"><table>

<tr><th>Tag</th><th>Named</th><th>Why</th><th>By</th><th>When</th></tr>

{% for w in withdrawn %}

<tr>

  <td class="px mute"><s>{{ w.name }}</s></td>

  <td>{% for h in w.heads %}<a class="chip" href="{{ repo.url }}/change/{{ h }}">{{ h|short }}</a> {% endfor %}</td>

  <td>{% if w.reason.is_empty() %}<span class="mute">—</span>{% else %}{{ w.reason }}{% endif %}</td>

  <td>{% if let Some(s) = w.signer %}<span class="sig sig-valid">✔</span> {{ s }}{% else %}<span class="sig sig-unsigned">○</span> unsigned{% endif %}</td>

  <td><time title="{{ w.when_ms|when_i }}">{{ w.when_ms|ago_i }}</time></td>