Administration: a sidebar of grouped pages, one page per section (closes #288) 737de0fac722

## Unreleased

- **Help: AI identities (#287):** a section on letting an AI agent work for you: keyless agents (a grant with `oh agent grant`, an agent home with `oxy auth grant`, ten-minute certified keys, nothing secret on disk), how its work shows (`via agent:NAME@YOU`), admitting it to a repository's trust policy (`oxy policy grant-subject`), agents with keys of their own (delegation), agent-marked tokens, approval gates, and revoking. "Letting the hub act for you" now says to export your identity again after delegating and upload that.

- **Settings › Keys says when each key was last used (#286):** like tokens, each linked key shows when it was linked, when the hub last accepted a push it signed (a change or a seal; "never" until then) and when the identity expires.

- **Settings › Security is balanced (#285):** every box runs the page's width: two-factor shows whether it is on in its head, with its field and button on one row; connected accounts are rows with Connect or Disconnect; signed-in browsers are rows with Sign out, and Sign out everywhere else sits in that box's head with the session limits under it.

use axum::extract::{Form, State};

use serde::Deserialize;

#[derive(Template)]

#[template(path = "admin.html")]

pub struct AdminPage {

    shell: Shell,

    accounts: Vec<accounts::Account>,

    orgs: Vec<accounts::Organisation>,

    mode: String,

    }

}

}

/// The audit log shows this many rows a page.

const AUDIT_PAGE: i64 = 50;

    let e = |e| Error::from_db(shell.clone(), e);

    let accounts_list = accounts::accounts(&app.db).await.map_err(e)?;

    let orgs = accounts::orgs(&app.db).await.map_err(e)?;

    let (security_contact, security_policy) = super::security_txt::settings(app).await;

    let (security_email, security_page) = super::security_txt::page_settings(app).await;

    Ok(Page(AdminPage {

        providers,

        security_contact,

        security_policy,

            };

            match crate::mail::compose(&asked, &current.smtp) {

                Ok(url) => url,

            }

        }

    };

        return admin_page(

            &app,

            shell,

            Some("The SMTP URL starts with smtp:// or smtps:// (file:///dir writes messages to a directory, for testing).".into()),

        )

        .await;

    }

    if !smtp.is_empty() && from.is_empty() {

    }

    crate::mail::save(&app, &smtp, &from).await.map_err(|e| Error::from_db(shell.clone(), e))?;

    accounts::audit(&app.db, Some(&me), "admin.mail", if smtp.is_empty() { "off" } else { "on" }, &from).await.ok();

}

/// `POST /admin/mail/test`: a message to the administrator's own address.

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

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

    if !crate::mail::enabled(&app) {

    }

    if me.email.is_empty() {

    }

    let base = app.config.base_url().to_string();

    let notice = match crate::mail::send_letter(

        Ok(()) => format!("Sent a test message to {}.", me.email),

        Err(e) => format!("Sending failed: {e}"),

    };

}

#[derive(Deserialize)]

    axum::extract::Query(q): axum::extract::Query<IndexQuery>,

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

    let shell = Shell::new(&app, "/admin", &viewer);

    require_admin(&viewer, &shell)?;

}

#[derive(Deserialize)]

    }

    accounts::set_setting(&app.db, "registration_mode", &f.mode).await.map_err(|e| Error::from_db(shell.clone(), e))?;

    accounts::audit(&app.db, Some(&me), "admin.registration", &f.mode, "").await.ok();

}

pub async fn invite(State(app): State<Shared>, viewer: Viewer, Form(f): Form<super::session::CsrfForm>) -> Result<Page<AdminPage>, Error> {

    let code = auth::random_hex(12);

    accounts::create_invitation(&app.db, &code, Some(me.id)).await.map_err(|e| Error::from_db(shell.clone(), e))?;

    accounts::audit(&app.db, Some(&me), "admin.invite", &code, "").await.ok();

}

#[derive(Deserialize)]

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

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

    let Some(target) = accounts::account_by_name(&app.db, f.username.trim()).await.map_err(|e| Error::from_db(shell.clone(), e))? else {

    };

    if target.id == me.id && matches!(f.action.as_str(), "ban" | "demote" | "disable" | "delete") {

    }

    let e = |e| Error::from_db(shell.clone(), e);

    // The hub must keep an admin who can sign in (oxygenhub#81).

        let others =

            accounts::accounts(&app.db).await.map_err(e)?.into_iter().filter(|a| a.is_admin && !a.blocked() && a.id != target.id).count();

        if others == 0 {

        }

    }

    if f.action == "delete" {

        if f.confirm.trim() != target.username {

        }

        let repos = crate::db::repos::list_by_owner(&app.db, &target.username).await.map_err(e)?;

        let orgs = accounts::orgs_owned_only_by(&app.db, target.id).await.map_err(e)?;

            return admin_page(

                &app,

                shell,

                Some(format!("Not deleted: {} still owns {}. Transfer or delete them first.", target.username, held.join(", "))),

            )

            .await;

        }

        accounts::delete_account(&app.db, target.id, &target.username).await.map_err(e)?;

        accounts::audit(&app.db, Some(&me), "admin.account.delete", &target.username, "").await.ok();

    }

    if f.action == "reset_link" {

        if target.blocked() {

        }

        let url = super::recovery::admin_reset_link(&app, &me, &target).await.map_err(e)?;

        return admin_page(

            &app,

            shell,

            Some(format!("Reset link for {} (works once, for 24 hours; shown only now): {url}", target.username)),

        )

        .await;

        _ => return Err(Error::bad(shell, "unknown action")),

    }

    accounts::audit(&app.db, Some(&me), &format!("admin.account.{}", f.action), &target.username, "").await.ok();

}

// ------------------------------------------------------------------ storage

    require_admin(&viewer, &shell)?;

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

    let outcome = super::assistants::apply(&app, &viewer, &site_assistants(), f).await.map_err(|e| Error::from_db(shell.clone(), e))?;

}

/// `POST /admin/variables`: the site's Flow variables (#102).

    require_admin(&viewer, &shell)?;

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

    let outcome = super::variables::apply(&app, &viewer, &site_assistants(), f).await.map_err(|e| Error::from_db(shell.clone(), e))?;

}

/// `POST /admin/secrets`: the site's Flow secrets (#107).

    require_admin(&viewer, &shell)?;

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

    let outcome = super::secrets::apply(&app, &viewer, &site_assistants(), f).await.map_err(|e| Error::from_db(shell.clone(), e))?;

}

/// `POST /admin/signin`: a sign-in provider's client id, secret and switch (#106).

    require_admin(&viewer, &shell)?;

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

    let outcome = super::signin::apply(&app, &viewer, f).await.map_err(|e| Error::from_db(shell.clone(), e))?;

}

/// `POST /admin/assistants/models`: what a provider offers, as JSON (#109).

        .route("/settings/notifications", get(inbox::unsubscribe).post(inbox::prefs))

        .route("/search", get(inbox::search))

        .route("/admin", get(admin::index))

        .route("/admin/invite", post(admin::invite))

        .route("/admin/account", post(admin::account))

        .route("/admin/storage", get(admin::storage).post(admin::maintain))

        .route("/admin/runners/{id}/state", post(runners::set_state))

        .route("/admin/runners/{id}/scope", post(runners::set_scope))

        .route("/admin/runners/{id}/limits", post(runners::set_limits))

        .route("/admin/mail/test", post(admin::test_mail))

        .route("/admin/assistants/models", post(admin::assistant_models))

        .route("/login/{provider}", get(signin::start))

        .route("/login/{provider}/callback", get(signin::callback))

        .route("/settings/security/connect/{provider}", get(signin::connect))

        .route("/settings/security/disconnect/{provider}", post(signin::disconnect))

        .route("/admin/runners/{id}/remove", post(runners::remove))

        .nest("/api/v1", crate::api::router(app.config.limits.asset_limit.0 as usize))

        // Drops (#279): `drops` is reserved, as an owner and as a repository name.

    } else {

        "Security contact saved: /.well-known/security.txt names it.".to_string()

    };

}

#[cfg(test)]

    let h = hub().await;

    let app = &h.app;

    let andy = register(app, "andy", "").await;

    assert!(page.contains("Mail is off"), "{page}");

    let csrf = csrf_of(&page);

    // A directory store for messages, as hub.toml's file:// would be.

    let (endpoint, seen) = mock_assistant().await;

    // The site level: an administrator adds Claude with a token.

    assert!(page.contains("AI assistants") && page.contains("Add an assistant"), "{page}");

    let csrf = csrf_of(&page);

    let add = |name: &str, extra: &str| {

    // Nothing to sign in with until an administrator sets a provider up.

    assert!(!get(app, "/login", None).await.body.contains("/login/github"));

    assert!(admin.contains("Sign in with") && admin.contains(&format!("http://127.0.0.1:{port}/login/github/callback")), "{admin}");

    let csrf = csrf_of(&admin);

    let r =

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

    for i in 0..60 {

        db::accounts::audit(&app.db, Some(&andy_row), "test.event", &format!("t{i}"), "").await.unwrap();

    }

    }

    assert!(page.contains(">t59<") && !page.contains(">t5<"), "the newest page only");

    let i = page.find("audit_before=").expect("an older link") + "audit_before=".len();

    let before: String = page[i..].chars().take_while(|c| c.is_ascii_digit()).collect();

    assert!(older.contains(">t5<") && !older.contains(">t59<"), "the next page: {older}");

}

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

    let ep = format!("http%3A%2F%2F127.0.0.1%3A{port}%2Fv1%2Fchat%2Fcompletions");

    assert!(page.contains("data-preset-select") && page.contains("Google Gemini") && page.contains("Other (enter the endpoint)"), "{page}");

    assert!(page.contains("LIST MODELS"));

    let csrf = csrf_of(&page);

    let app = &h.app;

    assert_eq!(get(app, "/.well-known/security.txt", None).await.status, StatusCode::NOT_FOUND, "no contact, no file");

    let andy = register(app, "andy", "").await;

    assert!(page.contains("No contact yet"), "the panel");

    let csrf = csrf_of(&page);

    let set = |contact: &'static str, policy: &'static str| {

    assert_eq!(got["env"], serde_json::json!({ "CC": "clang", "LANG": "C", "RUST_LOG": "debug" }), "{got}");

    // Removing a site variable from the admin page takes effect at the next claim.

    assert!(admin.contains("Variables") && admin.contains("<code>gcc</code>"), "{admin}");

    let (_, body) = page("/admin/variables", Some(format!("_csrf={}&action=delete&name=LANG", csrf_of(&admin)))).await;

    assert!(body.contains("LANG removed."), "{body}");

    // An administrator's link, for an account without a verified email.

    post(app, "/register", None, "username=bob&email=&password=bob-password-long-enough&setup=test-setup").await;

    assert!(admin.body.contains("value=\"reset_link\""));

    let r = post(app, "/admin/account", Some(&session), &format!("_csrf={}&username=bob&action=reset_link", csrf_of(&admin.body))).await;

    assert!(r.body.contains("Reset link for bob"), "{}", r.body);

| `/projects/{owner}`, `/projects/{owner}/{n}` | Projects of a person or organisation (§8.2) |

| `/search` | §11 |

| `/help` | Getting started with this hub's own address, remote name and certificate filled in (identity, pushing, cloning, proposals, delegating to the hub, pipelines and stamps), the keyboard, and a glossary for people coming from GitHub. Linked from the header band, the footer and the keyboard sheet |

### 6.4 Repository overview

{% import "assistants_panel.html" as ai %}

{% import "variables_panel.html" as va %}

{% import "secrets_panel.html" as se %}

{% block content %}

<div class="head"><h1>Administration <small>{{ accounts.len() }} accounts · {{ orgs.len() }} organisations · {{ repos }} repositories</small></h1></div>

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

<section class="panel" id="accounts">

  <h2>Accounts</h2>

  <div class="table"><table class="small"><tr><th>Username</th><th>Email</th><th>Flags</th><th>Last seen</th><th></th></tr>

  {% endfor %}

  </table></div>

</section>

<section class="panel" id="registration">

  <h2>Registration and invitations</h2>

  <form class="card" method="post" action="/admin/registration">

  <form class="card" method="post" action="/admin/invite"><input type="hidden" name="_csrf" value="{{ shell.csrf }}"><button type="submit">NEW INVITATION</button></form>

  {% if !invitations.is_empty() %}<ul class="plain small">{% for (code, used, at) in invitations %}<li><code>{{ code }}</code> {% if used.is_some() %}<span class="mute">used</span>{% else %}<a href="/register?invite={{ code }}">link</a>{% endif %} · {{ at|ago_i }}</li>{% endfor %}</ul>{% endif %}

</section>

<section class="panel" id="organisations">

  <h2>Organisations</h2>

  {% if orgs.is_empty() %}<p class="mute small">None yet.</p>{% else %}<ul class="plain">{% for o in orgs %}<li><img class="avatar xs" src="/avatar/{{ o.name }}" alt=""> <a href="/{{ o.name }}">{{ o.name }}</a> · <a class="small" href="/orgs/{{ o.name }}/settings">settings</a></li>{% endfor %}</ul>{% endif %}

</section>

<section class="panel" id="signin">

  <h2>Sign in with</h2>

  <p class="small mute">A first sign-in links the account with the same verified email, or makes an account when registration is open. Secrets are kept sealed.</p>

  </form>

  {% endfor %}

</section>

<section class="panel" id="mail">

  <h2>Mail</h2>

  <form class="card mail-panel" method="post" action="/admin/mail">

  <form class="card" method="post" action="/admin/mail/test"><input type="hidden" name="_csrf" value="{{ shell.csrf }}"><button type="submit"{% if !mail_enabled || my_email.is_empty() %} disabled{% endif %}>SEND A TEST{% if !my_email.is_empty() %} TO {{ my_email }}{% endif %}</button></form>

  <p class="small mute">{% if mail_enabled %}Mail is on: verification and reset links go by email.{% else %}Mail is off: verification and reset links are issued by hand.{% endif %} Off turns it off. Passwords and keys stay on the server and are never shown again. Every service is SMTP underneath, so any provider works: <code>smtps://USER:PASSWORD@HOST:465</code> for TLS from the start, or <code>smtp://USER:PASSWORD@HOST:587</code>, which the hub sends with STARTTLS required (add <code>?tls=opportunistic</code> or <code>?tls=none</code> to say otherwise; a relay on this machine needs none).</p>

</section>

<section class="panel" id="security">

  <h2>Security contact</h2>

  <form class="card" method="post" action="/admin/security">

  </form>

  <p class="small mute">{% if security_contact.is_empty() %}No contact yet, so there is no <code>security.txt</code>.{% else %}Published at <a href="/.well-known/security.txt">/.well-known/security.txt</a>.{% endif %} Researchers look there (RFC 9116) for where to report a vulnerability in this hub. Its expiry date renews itself.</p>

</section>

{% call va::panel("/admin", variables, shell.csrf, "Every repository's jobs get these, unless an organisation or repository sets the same name.") %}

{% call se::panel("/admin", secrets, shell.csrf, "Every repository's jobs may use these, unless an organisation or repository sets the same name.") %}

{% call ai::panel("/admin", assistants, shell.csrf, "Every repository on the site may ask these, unless an organisation or repository turns one off.") %}

<section class="panel" id="audit">

  <h2>Audit log</h2>

  <div class="table"><table class="small"><tr><th>When</th><th>Who</th><th>Action</th><th>Target</th><th>Detail</th></tr>

  {% for r in audit %}<tr><td><time title="{{ r.at_ms|when_i }}">{{ r.at_ms|ago_i }}</time></td><td>{{ r.actor }}</td><td><code>{{ r.action }}</code></td><td>{{ r.target }}</td><td class="mute">{{ r.detail }}</td></tr>{% endfor %}

  </table></div>

</section>

</div>

</div>

{% endblock %}

{% extends "base.html" %}

{% block title %}Backups · Administration{% endblock %}

{% block mainclass %} class="wide"{% endblock %}

{% block content %}

<div class="head"><h1>Backups <small>{{ owners.len()|plural("owner", "owners") }} · <a href="/admin">Administration</a></small></h1></div>

<p class="small mute">Each user and organisation backs up its own repositories, to a place it controls (docs/backups.md). Here is whether each one ran and how it went; what a run wrote stays with its owner. This site's own backup runs on its host, outside the hub.</p>

<section class="card-box">

  <div class="card-head"><h2>Owners' backups</h2><span class="count-chip">{{ owners.len() }}</span></div>

  <ul class="plain">{% for (owner, n) in uncovered %}<li><a href="/{{ owner }}">{{ owner }}</a> <span class="mute small">{{ n|plural("repository", "repositories") }}</span></li>{% endfor %}</ul>

  {% endif %}

</section>

{% endblock %}

{% extends "base.html" %}

{% import "diffusion_rows.html" as d %}

{% block title %}Diffusion · Administration{% endblock %}

{% block mainclass %} class="wide"{% endblock %}

{% block content %}

<div class="head"><h1>Diffusion <small>{{ upstreams.len()|plural("upstream", "upstreams") }} · <a href="/admin">Administration</a></small></h1></div>

<p class="small mute df-key">Each pill has two halves. Left, the upstream: <span class="df-pill"><span class="df-half df-green">checked</span></span> its own run passed, <span class="df-pill"><span class="df-half df-amber">untested</span></span> it has no checks, <span class="df-pill"><span class="df-half df-red">failing</span></span> its run failed. Right, the repository that pins it: <span class="df-pill"><span class="df-half df-green">passes</span></span> its run on the bump passed, <span class="df-pill"><span class="df-half df-red">fails</span></span> it failed, <span class="df-pill"><span class="df-half df-grey">testing</span></span> still running, <span class="df-pill"><span class="df-half df-green">up to date</span></span> nothing to bump.</p>

{% if upstreams.is_empty() %}<p class="empty">No repository on this hub is pinned by another yet.</p>{% endif %}

{% for (up, list, unverified) in upstreams %}

<h2><a href="/{{ up.owner }}/{{ up.name }}/diffusion">{{ up.owner }}/{{ up.name }}</a> <small>{{ list.len()|plural("consumer", "consumers") }}{% if *unverified %} · <span class="df-pill"><span class="df-half df-amber">untested</span></span>{% endif %}</small></h2>

{% call d::rows(list) %}

{% endfor %}

{% endblock %}

{% extends "base.html" %}

{% block title %}Images · Administration{% endblock %}

{% block content %}

{# The swarm (docs/backgrounds.md §2): the hub and the runners, and the

{% include "backdrop.html" %}

<div data-backdrop-avoid>

<div class="head"><h1>Runners <small>{{ images.len()|plural("image", "images") }} · {{ on_hub }} on the hub · <a href="/admin">Administration</a></small></h1></div>

<div class="bar"><span class="modes"><a href="/admin/runners">runners</a><a href="/admin/runners/images" class="on">images</a><a href="/admin/runners/settings">settings</a></span></div>

<p class="small mute">Every rootfs image a runner holds, the hub keeps, or a job ran on in the last 90 days, newest use first. {% if swarm.is_empty() %}No runner shares images peer to peer yet: give one a <code>[runner.swarm]</code> section.{% else %}Sharing images peer to peer: {% for s in swarm %}{{ s }}{% if !loop.last %}, {% endif %}{% endfor %}.{% endif %} Send an image to the hub with <code>flow rootfs push HASH</code>.</p>

{% if images.is_empty() %}

</table></div>

{% endif %}

</div>

{% endblock %}

{% extends "base.html" %}

{% block title %}{{ r.name }} · Runners{% endblock %}

{% block mainclass %} class="wide"{% endblock %}

{% block content %}

<div class="head"><h1>{{ r.name }} <small><span class="runner-status st-{{ r.status() }}">{{ r.status() }}</span> · <a href="/admin/runners">Runners</a></small></h1></div>

<section class="panel">

  <dl class="facts">

    <dt>Signing key</dt><dd>{% if r.key.is_empty() %}<span class="mute">bound on its first signed receipt</span>{% else %}<code class="full">{{ r.key }}</code> {{ r.key_name }}{% endif %}</dd>

  {% if let Some(b) = older %}<p><a href="?before={{ b }}">Older jobs</a></p>{% endif %}

  {% endif %}

</section>

{% endblock %}

{% extends "base.html" %}

{% block title %}Runner settings · Administration{% endblock %}

{% block content %}

<div class="head"><h1>Runners <small><a href="/admin">Administration</a></small></h1></div>

<div class="bar"><span class="modes"><a href="/admin/runners">runners</a><a href="/admin/runners/images">images</a><a href="/admin/runners/settings" class="on">settings</a></span></div>

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

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

  <h2>Repositories that run Flow</h2>

  {% if flow_repos.is_empty() %}<p class="mute">None listed in hub.toml; each repository's administrator switches Flow on in its Settings.</p>{% else %}<ul class="plain">{% for r in flow_repos %}<li><code>{{ r }}</code></li>{% endfor %}</ul><p class="small mute">From hub.toml's <code>[flow] repos</code>; others are switched on in each repository's Settings.</p>{% endif %}

</section>

{% endblock %}

{% extends "base.html" %}

{% block title %}Runners · Administration{% endblock %}

{% block mainclass %} class="wide"{% endblock %}

{% block content %}

<div class="head"><h1>Runners <small>{{ runners.len()|plural("runner", "runners") }} · <a href="/admin">Administration</a></small></h1></div>

<div class="bar"><span class="modes"><a href="/admin/runners" class="on">runners</a><a href="/admin/runners/images">images</a><a href="/admin/runners/settings">settings</a></span></div>

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

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

    <button type="submit" class="primary-btn">Create a registration token</button></form>

  {% if !pending.is_empty() %}<p class="small mute">Unused tokens: {% for (by, made, expires) in pending %}by {{ by }} {{ made|ago_i }}, expires {{ expires|when_i }}{% if !loop.last %}; {% endif %}{% endfor %}</p>{% endif %}

</section>

{% endblock %}

{% extends "base.html" %}

{% block title %}Storage · Administration{% endblock %}

{% block content %}

<div class="head"><h1>Storage <small>{{ rows.len() }} repositories · {{ total|bytes }}</small></h1></div>

<p><a href="/admin">← administration</a></p>

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

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

  {% endfor %}

  </tbody>

</table>

{% endblock %}

.sections .panel form.card { max-width: 720px; }

.sections > details > form.card { max-width: none; }

/* A repository's settings (#278): grouped pages in a sidebar, one page beside it. */

.settings-layout { display: grid; grid-template-columns: 200px minmax(0, 1fr); gap: 28px; align-items: start; }

.settings-nav { position: sticky; top: 14px; display: flex; flex-direction: column; gap: 14px; }

.settings-group h2 { font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .08em; color: var(--mute); margin: 0 0 4px; padding: 0 12px; }