Keys say when each was last used; Help explains AI identities (closes #286, closes #287) b349e15a3eab

-- When the hub last received something a linked key signed (oxygenhub#286):

-- a pushed change or a seal. NULL until then.

ALTER TABLE identities ADD COLUMN last_used_ms BIGINT;

-- When the hub last received something a linked key signed (oxygenhub#286):

-- a pushed change or a seal. NULL until then.

ALTER TABLE identities ADD COLUMN last_used_ms INTEGER;

- **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.

    /// When the hub last received something this key signed (#286).

    #[sqlx(default)]

    pub last_used_ms: Option<i64>,

}

impl LinkedIdentity {

    /// When the identity itself expires, if it says.

    pub fn expires_ms(&self) -> Option<i64> {

        oxy_core::identity::Identity::decode(&self.object).ok()?.expires.map(|e| e as i64)

    }

}

/// Note that the hub received something signed by each of `keys` (#286):

/// linked keys only, at most once a minute each.

pub async fn identities_used(pool: &Pool, keys: &[String]) -> sqlx::Result<()> {

    let now = now_ms();

    for k in keys {

        sqlx::query("UPDATE identities SET last_used_ms = $1 WHERE key = $2 AND (last_used_ms IS NULL OR last_used_ms < $3)")

            .bind(now)

            .bind(k)

            .bind(now - 60_000)

            .execute(pool)

            .await?;

    }

    Ok(())

    /// The keys that signed what a push to each repository (by name)

    /// brought, noted when it is vetted and recorded once it is accepted

    /// (#286, Settings › Keys' "last used").

    signers: Arc<std::sync::Mutex<std::collections::HashMap<String, std::collections::BTreeSet<String>>>>,

            signers: Arc::default(),

        let keys: std::collections::BTreeSet<String> = bundle

            .changes

            .iter()

            .flat_map(|(_, sigs)| sigs.iter())

            .chain(bundle.attests.iter().flat_map(|a| a.sigs.iter()))

            .map(|sig| sig.key.to_hex())

            .collect();

        if !keys.is_empty() {

            self.signers.lock().unwrap().entry(name.to_string()).or_default().extend(keys);

        }

        // The keys that signed what it brought were used (#286): linked

        // ones show it under Settings › Keys.

        let signers = self.signers.lock().unwrap().remove(name);

        if let Some(keys) = signers.filter(|_| report.results.iter().any(|r| r.ok)) {

            let pool = self.pool.clone();

            let keys: Vec<String> = keys.into_iter().collect();

            tokio::spawn(async move {

                if let Err(e) = db::accounts::identities_used(&pool, &keys).await {

                    tracing::warn!("noting keys used: {e}");

                }

            });

        }

    /// An agent's own home, keyless, with its grant kept (#287).

    pub fn agent_home_cmd(&self) -> String {

        format!(

            "export OXY_HOME=~/.oxy-agents/claude\noxy config --user author.signer keyless\noxy config --user keyless.hub {base}\noxy config --user core.sign seal\noxy auth grant {base}   # paste the token, then Ctrl-D",

            base = self.base

        )

    }

    /// A repository's trust policy admitting an agent's certified keys (#287).

    pub fn subject_grant_cmd(&self) -> String {

        format!(

            "curl -fsSL {}/.well-known/oxyhub-key -o hub.identity\noxy policy grant-subject agent:claude@{} --issuer hub.identity --scope changes,refs",

            self.base, self.who

        )

    }

    // oxygenhub#286: a linked key is "last used" when a push it signed is

    // accepted.

    let keys = get(app, "/settings/keys", Some(&andy)).await.body;

    assert!(keys.contains("last used never") && keys.contains("never expires"), "{keys}");

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

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

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

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

    let mut used = String::new();

    for _ in 0..100 {

        used = get(app, "/settings/keys", Some(&andy)).await.body;

        if !used.contains("last used never") {

            break;

        }

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

    }

    assert!(used.contains("last used <time"), "{used}");

    for id in ["start", "identity", "push", "clone", "proposals", "delegate", "agents", "flow", "keys", "glossary"] {

    // oxygenhub#287: AI identities, with this hub in the commands.

    assert!(help.contains("oh agent grant claude") && help.contains(&format!("oxy auth grant {}", h.base)), "agent grants");

    assert!(help.contains("oxy policy grant-subject agent:claude@OWNER --issuer hub.identity"), "subject grants");

    assert!(help.contains("via agent:claude@OWNER"), "how agent work shows");

  <a href="#agents">AI identities</a>

  <p>That makes a new version of your identity: export it in the same checkout (<code>oxy identity export</code>) and upload that file under Settings › Keys, signing the challenge there too, so the hub sees the delegation. The hub's key file is not the one to upload. You can withdraw it at any time with <code>oxy identity delegate remove</code>; a repository's trust policy still decides whether a delegated change may update a bookmark.</p>

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

  <h2>AI identities</h2>

  <p>An AI agent (a coding assistant, a bot) can work on your repositories in its own name and in yours: its changes are signed, they say which agent made them, and you decide what it may do and for how long. Nothing it is given is a password or a key of yours.</p>

  <h3>Keyless agents (recommended)</h3>

  <p>A keyless agent holds no key at all. You give it a <strong>grant</strong>: a token your own key signs, valid for a time you choose. Whenever the agent signs, it makes a fresh key, the hub certifies it for ten minutes under your grant, and the key is thrown away; a stolen home holds nothing that signs by itself.</p>

  <p>On your side, name the agent and how long it may act for you (the token is printed once):</p>

  {% let cmd = "oh agent grant claude --for 30d --scope changes,seal,refs" %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>Give the agent its own oxy home (never your own), and keep the token there; it is read from standard input, so it stays out of the shell's history:</p>

  {% let cmd = self.agent_home_cmd() %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>The agent then commits and pushes with <code>OXY_HOME</code> set to its home. Its changes are authored as you and sealed <code>via agent:claude@{{ who }}</code>, which history, proposals and your profile show. <code>oh agent list</code> shows your grants; <code>oh agent revoke ID</code> ends one at once, and a grant ends by itself when its time is up.</p>

  <h3>Where it may push</h3>

  <p>A repository with a trust policy accepts an agent's work only if the policy names it. Grant the agent's subject, with this hub as the issuer, from a checkout of the repository:</p>

  {% let cmd = self.subject_grant_cmd() %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>A repository without a policy takes any signed change its token may push.</p>

  <h3>Agents with a key of their own</h3>

  <p>An agent that keeps its own identity acts for you through a <strong>delegation</strong>: from your checkout, <code>oxy identity delegate add agent.identity --scope changes --expires 7d</code>, then link your identity again under {% if shell.user.is_some() %}<a href="/settings/keys">Settings › Keys</a>{% else %}Settings › Keys{% endif %}. <code>oxy identity delegate remove KEY</code> withdraws it. Keyless grants are simpler and leave nothing behind.</p>

  <h3>Tokens, notifications and gates</h3>

  <ul>

    <li>A personal access token an agent uses can be marked <strong>agent</strong> under {% if shell.user.is_some() %}<a href="/settings/tokens">Settings › Tokens</a>{% else %}Settings › Tokens{% endif %}: proposals it opens and comments it makes reach your inbox and email like anyone else's.</li>

    <li>An approval gate is for a person: an agent's token cannot approve or reject one unless a repository's maintainers allow it under Settings › Gates & agents, and each decision still says which agent made it.</li>

    <li>Commits whose message says a skip marker (<code>[skip flow]</code>) start no pipeline run; agents should leave them out unless asked.</li>

  </ul>

</section>

        <div class="small mute">linked <time title="{{ k.linked_ms|when_i }}">{{ k.linked_ms|ago_i }}</time> · last used {% if let Some(u) = k.last_used_ms %}<time title="{{ u|when_i }}">{{ u|ago_i }}</time>{% else %}never{% endif %} · {% if let Some(x) = k.expires_ms() %}expires {{ x|when_i }}{% else %}never expires{% endif %}</div>