Who did the work: via AGENT, rotated identities link themselves, a Flow badge 8933faff2043

    /// Signed for the author by a delegate (an agent), when it was.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub via: Option<Via>,

}

/// A delegate that signed a change for its author (Oxygen spec §14.2).

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

pub struct Via {

    pub name: String,

    pub key: String,

    /// The delegation's scope, `changes` for an agent.

    pub scope: String,

    pub expires_ms: Option<u64>,

    /// The delegation has since been revoked or withdrawn.

    pub revoked: bool,

        via: c.via.as_ref().map(|v| Via {

            name: v.name.clone(),

            key: v.key.clone(),

            scope: v.scope.clone(),

            expires_ms: v.expires_ms,

            revoked: v.revoked,

        }),

        // Authors whose identity is a successor (a rotation, a renewal, a

        // delegation) of an earlier one: each step kept the key pair, so

        // if the chain reaches a linked key it is the same person, and the

        // successor is linked too, without re-uploading it (hub spec §5.3).

        let successors: Vec<(String, String, String, Vec<u8>, String)> = self

            .repos

            .open(&parsed)

            .map(|r| {

                let mut seen = std::collections::HashSet::new();

                let mut out = Vec::new();

                for h in &report.imported {

                    let Ok(meta) = r.store().get_change_meta(h) else { continue };

                    let mut key = meta.author;

                    while !key.is_zero() && seen.insert(key) {

                        let Ok(id) = r.store().get_identity(&key) else { break };

                        let Some(prev) = id.previous else { break };

                        let Ok(before) = r.store().get_identity(&prev) else { break };

                        if before.ed25519_pk != id.ed25519_pk || before.mldsa65_pk != id.mldsa65_pk {

                            break;

                        }

                        out.push((key.to_hex(), id.name.clone(), id.email.clone(), id.encode(), prev.to_hex()));

                        key = prev;

                    }

                }

                out

            })

            .unwrap_or_default();

            }

            // Oldest first: a link made for one step lets the next step link.

            for (key, name, email, object, prev) in successors.iter().rev() {

                let Ok(None) = db::accounts::identity_by_key(&pool, key).await else { continue };

                let Ok(Some(earlier)) = db::accounts::identity_by_key(&pool, prev).await else { continue };

                match db::accounts::link_identity(&pool, earlier.account_id, key, name, email, object).await {

                    Ok(()) => {

                        tracing::info!("linked identity {} to account {} as a successor of {}", &key[..12], earlier.account_id, &prev[..12]);

                        db::accounts::audit(&pool, None, "identity.rotated", key, &format!("successor of {}", &prev[..12])).await.ok();

                    }

                    Err(e) => tracing::warn!("linking successor identity {}: {e}", &key[..12]),

                }

            via: None,

/// Who signed for the author when it was not the author: a delegate, such

/// as an agent, named by its identity, with the delegation that let it

/// (Oxygen's agent workflows doc §6).

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

pub struct ViaView {

    pub name: String,

    pub email: String,

    pub key: String,

    pub short: String,

    /// The delegation's scope as written, `changes` for an agent.

    pub scope: String,

    pub expires_ms: Option<u64>,

    /// The signing key was revoked, or the delegation is no longer in the

    /// author's identity: the change deserves a second look.

    pub revoked: bool,

}

impl ViaView {

    /// The delegation, as the change page's `via` row says it.

    pub fn delegation(&self) -> String {

        if self.revoked {

            return "delegation revoked".into();

        }

        match self.expires_ms {

            Some(e) => format!("delegate for {}, until {}", self.scope, when_utc(e)),

            None => format!("delegate for {}", self.scope),

        }

    }

    /// What hovering the badge says.

    pub fn title(&self) -> String {

        let until = match self.expires_ms {

            Some(e) => format!(", until {}", when_utc(e)),

            None => String::new(),

        };

        if self.revoked {

            format!("signed by {} as a delegate of the author; that delegation has since been revoked", self.name)

        } else {

            format!("signed by {} as a delegate of the author ({}{until}), key {}", self.name, self.scope, self.short)

        }

    }

}

/// `2026-10-04 20:12Z` for a wall time in milliseconds.

fn when_utc(ms: u64) -> String {

    time::OffsetDateTime::from_unix_timestamp_nanos(ms as i128 * 1_000_000)

        .ok()

        .and_then(|t| t.format(&time::macros::format_description!("[year]-[month]-[day] [hour]:[minute]Z")).ok())

        .unwrap_or_else(|| ms.to_string())

}

/// The delegate that signed `hash` for the author, when one did.

pub fn via(repo: &Repo, author: &KeyId, sig: &SigView) -> Option<ViaView> {

    let SigView::Valid { key, name, revoked, .. } = sig else { return None };

    if author.is_zero() || *key == author.to_hex() {

        return None;

    }

    let signer = KeyId::from_hex(key)?;

    let entry = repo.store().get_identity(author).ok().and_then(|a| a.delegate(&signer).copied());

    let email = repo.store().get_identity(&signer).map(|i| i.email).unwrap_or_default();

    Some(ViaView {

        name: name.clone(),

        email,

        key: key.clone(),

        short: signer.short(12),

        scope: entry.map(|d| d.scope.to_string()).unwrap_or_else(|| "changes".into()),

        expires_ms: entry.and_then(|d| d.expires),

        revoked: *revoked || entry.is_none(),

    })

}

    /// Signed for the author by a delegate (an agent), when it was.

    pub via: Option<ViaView>,

    let signature = signature(repo, hash);

    let via = via(repo, &meta.author, &signature);

        signature,

        via,

    /// Of `changes`, how many a delegate signed for this author, by the

    /// delegate's name (an agent's work stays the author's, and is shown).

    pub via: Vec<(String, usize)>,

/// Authors of the changes of a state, most changes first. A change a

/// delegate signed counts for its author, and the delegate is named under

/// them: the signing key is read, not verified (the change rows do that).

    let mut names: HashMap<KeyId, String> = HashMap::new();

    for (hash, meta) in state.changes() {

        let entry = by.entry(id).or_insert_with(|| Contributor { name, key: a.key.clone(), changes: 0, account: None, via: Vec::new() });

        entry.changes += 1;

        if !meta.author.is_zero() {

            let signer = repo.store().signatures(hash).ok().and_then(|s| s.first().map(|s| s.key)).filter(|k| *k != meta.author);

            if let Some(k) = signer {

                let who =

                    names.entry(k).or_insert_with(|| repo.store().get_identity(&k).map(|i| i.name).unwrap_or_else(|_| k.short(12))).clone();

                match entry.via.iter_mut().find(|(n, _)| *n == who) {

                    Some((_, n)) => *n += 1,

                    None => entry.via.push((who, 1)),

                }

            }

        }

    for c in &mut out {

        c.via.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));

    }

/// `/{owner}/{name}/flow/badge.svg`: the latest run on the default

/// bookmark as a small SVG for a README, for whoever may read the

/// repository. `passed` green, `failed` or `error` red, a run still going

/// blue, none grey.

pub async fn badge(

    State(app): State<Shared>,

    viewer: Viewer,

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

) -> Result<axum::response::Response, Error> {

    use axum::response::IntoResponse;

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

    let (_repo, row, _role) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    let latest = fdb::latest_on(&app.db, row.id, &row.default_bookmark).await.map_err(|e| Error::from_db(shell.clone(), e))?;

    let (text, colour) = match latest.as_ref().map(|r| r.status.as_str()) {

        Some("passed") => ("passing", "#2da44e"),

        Some("failed") | Some("error") => ("failing", "#cf222e"),

        Some("cancelled") => ("cancelled", "#6e7781"),

        Some(_) => ("running", "#0969da"),

        None => ("no runs", "#6e7781"),

    };

    let label = "OxygenFlow";

    let (lw, tw) = (label.len() as u32 * 7 + 10, text.len() as u32 * 7 + 10);

    let svg = format!(

        r##"<svg xmlns="http://www.w3.org/2000/svg" width="{w}" height="20" role="img" aria-label="{label}: {text}"><title>{label}: {text}</title><rect width="{lw}" height="20" rx="3" fill="#555"/><rect x="{lw}" width="{tw}" height="20" rx="3" fill="{colour}"/><rect x="{lw}" width="4" height="20" fill="{colour}"/><g fill="#fff" font-family="Verdana,DejaVu Sans,sans-serif" font-size="11" text-anchor="middle"><text x="{lx}" y="14">{label}</text><text x="{tx}" y="14">{text}</text></g></svg>"##,

        w = lw + tw,

        lx = lw / 2,

        tx = lw + tw / 2,

    );

    Ok((

        [(axum::http::header::CONTENT_TYPE, "image/svg+xml; charset=utf-8"), (axum::http::header::CACHE_CONTROL, "no-cache, max-age=60")],

        svg,

    )

        .into_response())

}

        .route("/{owner}/{name}/flow/badge.svg", get(flow::badge))

                via: c.via.as_ref().map(|v| hub_api::Via {

                    name: v.name.clone(),

                    key: v.key.clone(),

                    scope: v.scope.clone(),

                    expires_ms: v.expires_ms,

                    revoked: v.revoked,

                }),

    // The successor was pushed with a change it authored? Not yet: link it

    // by hand here, as before; the auto-link is checked further down.

/// A rotation reaches the hub with the next push: an author whose identity

/// is a successor of a linked one, with the same key pair, is linked

/// without another challenge. An agent's change shows who signed for the

/// author, on the change page, in history rows and over the API.

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

async fn a_rotated_identity_links_itself_and_an_agent_s_change_says_via() {

    hermetic();

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

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

    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 r = send(app, "POST", "/register", None, Some("username=andy&email=a%40example.com&password=correct-horse-battery")).await;

    assert!(r.cookie.is_some());

    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 home = tempfile::tempdir().unwrap();

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

    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();

    client.commit("first", &[]).unwrap();

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

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

    let id1 = client.identity(&key1).unwrap();

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

    // An agent with its own key; Andy delegates (a rotation) and commits.

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

    let mut agent_repo = Repo::init(&work.path().join("agent-scratch")).unwrap().with_home(agent_home.path());

    let (agent_key, agent_id) = agent_repo.create_identity("Antigravity", "[email protected]", IdentityScope::User).unwrap();

    client.delegate_add(agent_id, oxy_core::identity::Scope::CHANGES, None).unwrap();

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

    assert_ne!(key1, key2);

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

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

    let by_andy = client.commit("second, by Andy", &[]).unwrap();

    // The agent commits in Andy's checkout: Andy as author, its own signature.

    let mut as_agent = Repo::open(work.path()).unwrap().with_home(agent_home.path());

    as_agent.set_user_config("author.signer", &agent_key.to_hex()).unwrap();

    as_agent.set_user_config("core.sign", "change").unwrap();

    write(work.path(), "b.txt", b"by the agent\n");

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

    let by_agent = as_agent.commit("third, by the agent", &[]).unwrap();

    // Andy pushes both.

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

    tokio::time::sleep(std::time::Duration::from_millis(300)).await;

    // The successor is linked to Andy's account by the push.

    let linked = db::accounts::identity_by_key(&app.db, &key2.to_hex()).await.unwrap();

    assert_eq!(linked.map(|l| l.account_id), Some(andy_id), "the rotated identity links itself");

    assert!(db::accounts::identity_by_key(&app.db, &agent_key.to_hex()).await.unwrap().is_none(), "an agent's key is nobody's account");

    // The change page: Andy as author, a via row naming the agent.

    let page = send(app, "GET", &format!("/andy/demo/change/{}", by_agent.to_hex()), None, None).await.body;

    assert!(page.contains("<dt>via</dt>"), "{page}");

    assert!(page.contains("Antigravity") && page.contains("delegate for changes"), "{page}");

    assert!(page.contains("href=\"/andy\""), "the author is Andy's account: {page}");

    let andy_page = send(app, "GET", &format!("/andy/demo/change/{}", by_andy.to_hex()), None, None).await.body;

    assert!(!andy_page.contains("<dt>via</dt>"), "{andy_page}");

    // History rows and the API say so too.

    let rows = send(app, "GET", "/andy/demo/changes/main", None, None).await.body;

    assert!(rows.contains("via Antigravity"), "{rows}");

    let hist = send(app, "GET", "/api/v1/repos/andy/demo/history/main", None, None).await.body;

    let v: serde_json::Value = serde_json::from_str(&hist).unwrap();

    let agent_change = v["changes"].as_array().unwrap().iter().find(|c| c["hash"] == by_agent.to_hex()).unwrap();

    assert_eq!(agent_change["via"]["name"], "Antigravity");

    assert_eq!(agent_change["via"]["scope"], "changes");

    assert_eq!(agent_change["author"]["account"], "andy");

    // Contributors: the agent's change counts for Andy, named under him.

    let overview = send(app, "GET", "/andy/demo", None, None).await.body;

    assert!(overview.contains("via Antigravity 1"), "{overview}");

    // The badge: no runs yet.

    let badge = send(app, "GET", "/andy/demo/flow/badge.svg", None, None).await;

    assert_eq!(badge.status, StatusCode::OK);

    assert!(badge.body.contains("<svg") && badge.body.contains("no runs"), "{}", badge.body);

}

An identity can be linked to at most one account. Rotation (`oxy identity rotate`, `renew`, `delegate add|remove`) produces a successor identity whose object names the old key. When a push brings changes authored by a successor of a linked identity, and every step of the chain kept the key pair, the hub links the successor to the same account itself and records `identity.rotated` in the audit log: delegating to an agent never breaks attribution and needs no re-upload. A rotation to a fresh key pair (`oxy identity rotate`) still needs the new identity linked with a challenge.

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses (an unknown route 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`, `/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}`, `/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, `/cards` to 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), `/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), `/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}/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.

`/{owner}/{name}/flow/badge.svg` is a small SVG of the latest run on the default bookmark (`passing`, `failing`, `running`, `no runs`) for a README, for whoever may read the repository. It is a convenience, with the weakness of every badge; the stamps below are the real thing.

    <dt>Author</dt><dd>{% if let Some(a) = c.view.author.account %}<a href="/{{ a }}">{{ c.view.author.name }}</a> <span class="tag">@{{ a }}</span>{% else %}{{ c.view.author.name }}{% endif %}{% if !c.view.author.email.is_empty() %} <span class="mute">&lt;{{ c.view.author.email }}&gt;</span>{% endif %}{% if !c.view.author.key.is_empty() && c.view.author.account.is_none() %} <span class="tag" title="The key that signed this change is not linked to any account.">key not linked</span>{% if shell.user.is_some() %} <a class="small" href="/settings/keys">link your key</a>{% endif %}{% endif %}</dd>{% if let Some(v) = c.view.via %}

    <dt>via</dt><dd><span class="mute" aria-hidden="true">↳</span> <span class="tag{% if v.revoked %} bad{% endif %}" title="{{ v.title() }}">agent</span> {{ v.name }}{% if !v.email.is_empty() %} <span class="mute">&lt;{{ v.email }}&gt;</span>{% endif %} <span class="mute small">· {{ v.delegation() }} · key {{ v.short }}</span></dd>{% endif %}

      <li>{% if let Some(u) = c.account %}<a href="/{{ u }}"><img class="avatar sm" src="/avatar/{{ u }}" alt="" width="20" height="20"> {{ u }}</a> <span class="mute small">{{ c.name }}</span>{% else %}<span class="avatar-none" aria-hidden="true">○</span> {{ c.name }}{% endif %} <span class="mute small" title="changes">· {{ c.changes }}</span>{% if !c.via.is_empty() %}<br><span class="mute small">via {% for v in c.via %}{{ v.0 }} {{ v.1 }}{% if !loop.last %}, {% endif %}{% endfor %}</span>{% endif %}</li>

    <div class="meta"><span class="who">{% if let Some(a) = c.author.account %}<a href="/{{ a }}">{{ c.author.name }}</a>{% else %}{{ c.author.name }}{% endif %}{% if let Some(v) = c.via %} <span class="mute">via {{ v.name }}</span> <span class="tag{% if v.revoked %} bad{% endif %}" title="{{ v.title() }}">agent</span>{% endif %}</span> · <time title="{{ c.when_ms|when }}">{{ c.when_ms|ago }}</time></div>