Scoped, expiring delegates, and revocation by the delegator 7ba155f20aa0

`oxy identity renew --expires 365` sets an expiry, `oxy identity delegate add agent.identity --scope changes --expires 8h`

lets another key sign changes for you (an AI agent, say) for a while without ever being able

to move a bookmark, and `oxy identity revoke` retires a key. With several root

/// What a delegate may do on the delegator's behalf (spec §14.2): a set of

/// `changes` (sign individual changes), `seal` (seal batches of them) and

/// `refs` (reference and tag attestations). An agent gets `changes` alone,

/// so it can never move a reference, whatever its owner may do.

#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]

pub struct Scope(u8);

impl Scope {

    pub const NONE: Scope = Scope(0);

    pub const CHANGES: Scope = Scope(1);

    pub const REFS: Scope = Scope(2);

    pub const SEAL: Scope = Scope(4);

    /// Everything: what a delegate could do before scopes existed.

    pub const ALL: Scope = Scope(7);

    const NAMES: [(Scope, &'static str); 3] = [

        (Scope::CHANGES, "changes"),

        (Scope::REFS, "refs"),

        (Scope::SEAL, "seal"),

    ];

    pub fn has(self, other: Scope) -> bool {

        self.0 & other.0 == other.0

    }

    pub fn is_empty(self) -> bool {

        self.0 == 0

    }

    /// The names in the set, in the order they are written.

    pub fn names(self) -> Vec<&'static str> {

        Self::NAMES

            .iter()

            .filter(|(s, _)| self.has(*s))

            .map(|(_, n)| *n)

            .collect()

    }

    fn named(name: &str) -> Option<Scope> {

        Self::NAMES

            .iter()

            .find(|(_, n)| *n == name)

            .map(|(s, _)| *s)

    }

    /// `changes,refs` (also with spaces); `all` is every scope.

    pub fn parse(s: &str) -> Result<Scope, String> {

        let mut out = Scope::NONE;

        for part in s.split(',').map(str::trim).filter(|p| !p.is_empty()) {

            if part == "all" {

                return Ok(Scope::ALL);

            }

            match Self::named(part) {

                Some(sc) => out = out | sc,

                None => return Err(format!("unknown scope {part:?}: use changes, refs or seal")),

            }

        }

        if out.is_empty() {

            return Err("a delegate needs at least one scope: changes, refs or seal".into());

        }

        Ok(out)

    }

}

impl std::ops::BitOr for Scope {

    type Output = Scope;

    fn bitor(self, rhs: Scope) -> Scope {

        Scope(self.0 | rhs.0)

    }

}

impl std::fmt::Display for Scope {

    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

        f.write_str(&self.names().join(","))

    }

}

impl std::fmt::Debug for Scope {

    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

        write!(f, "Scope({self})")

    }

}

/// A key allowed to act for an identity, within `scope`, until `expires`

/// (wall milliseconds; `None` for as long as the delegation stands).

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

pub struct Delegate {

    pub key: KeyId,

    pub scope: Scope,

    pub expires: Option<u64>,

}

impl Delegate {

    /// A delegate with every scope and no expiry of its own.

    pub fn full(key: KeyId) -> Delegate {

        Delegate {

            key,

            scope: Scope::ALL,

            expires: None,

        }

    }

    /// Whether the delegation covers `scope` at `at_ms`.

    pub fn allows(&self, scope: Scope, at_ms: u64) -> bool {

        self.scope.has(scope) && !self.expires.is_some_and(|e| at_ms > e)

    }

    fn to_value(self) -> Value {

        Value::map([

            (0, Value::Bytes(self.key.0.to_vec())),

            (

                1,

                Value::Array(

                    self.scope

                        .names()

                        .into_iter()

                        .map(|n| Value::Text(n.to_string()))

                        .collect(),

                ),

            ),

            (2, self.expires.map(Value::Uint).unwrap_or(Value::Null)),

        ])

    }

    /// An entry, or a bare KeyId as identities carried before scopes

    /// existed, which meant every scope.

    fn from_value(v: &Value) -> Result<Delegate, ObjectError> {

        if let Value::Bytes(_) = v {

            return Ok(Delegate::full(oref(v, "delegate")?));

        }

        let m = v

            .as_map()

            .ok_or_else(|| ObjectError::Schema("delegate: expected map".into()))?;

        let key = oref(field(m, 0, "delegate key")?, "delegate key")?;

        let mut scope = Scope::NONE;

        for n in array(field(m, 1, "delegate scope")?, "delegate scope")? {

            let n = text(n, "delegate scope")?;

            scope = scope

                | Scope::named(n)

                    .ok_or_else(|| ObjectError::Schema(format!("delegate: unknown scope {n:?}")))?;

        }

        let expires = match field(m, 2, "delegate expires")? {

            v if v.is_null() => None,

            v => Some(uint(v, "delegate expires")?),

        };

        Ok(Delegate {

            key,

            scope,

            expires,

        })

    }

}

    pub delegates: Vec<Delegate>,

}

/// Sorted by key, one entry per key.

fn tidy(mut delegates: Vec<Delegate>) -> Vec<Delegate> {

    delegates.sort_by_key(|d| d.key);

    delegates.dedup_by(|a, b| a.key == b.key);

    delegates

    /// The delegation to `key`, if any.

    pub fn delegate(&self, key: &KeyId) -> Option<&Delegate> {

        self.delegates.iter().find(|d| d.key == *key)

    }

    /// Whether `key` may act for this identity within `scope` at `at_ms`.

    pub fn delegates_to(&self, key: &KeyId, scope: Scope, at_ms: u64) -> bool {

        self.delegate(key).is_some_and(|d| d.allows(scope, at_ms))

    }

                Value::Array(self.delegates.iter().map(|d| d.to_value()).collect()),

        let delegates = tidy(

            array(field(m, 8, "delegates")?, "delegates")?

                .iter()

                .map(Delegate::from_value)

                .collect::<Result<Vec<_>, _>>()?,

        );

    pub fn successor(

        &self,

        delegates: Vec<Delegate>,

        expires: Option<u64>,

        created: u64,

    ) -> Identity {

            delegates: tidy(delegates),

        other.delegates.push(Delegate::full(ObjectRef([9; 32])));

    }

    #[test]

    fn delegates_carry_scope_and_expiry_and_bare_keys_mean_every_scope() {

        let sk = fixed_key();

        let mut id = sk.identity("Ada", "[email protected]", 1_700_000_000_000);

        let agent = ObjectRef([7; 32]);

        let host = ObjectRef([3; 32]);

        id.delegates = vec![

            Delegate {

                key: agent,

                scope: Scope::CHANGES,

                expires: Some(2_000),

            },

            Delegate {

                key: host,

                scope: Scope::CHANGES | Scope::REFS,

                expires: None,

            },

        ];

        let d = Identity::decode(&id.encode()).unwrap();

        assert_eq!(d.delegates.len(), 2);

        assert!(d.delegates_to(&agent, Scope::CHANGES, 1_000));

        assert!(!d.delegates_to(&agent, Scope::CHANGES, 2_001), "expired");

        assert!(!d.delegates_to(&agent, Scope::REFS, 1_000));

        assert!(!d.delegates_to(&agent, Scope::SEAL, 1_000));

        assert!(d.delegates_to(&host, Scope::REFS, u64::MAX));

        assert!(!d.delegates_to(&host, Scope::SEAL, 0));

        assert!(!d.delegates_to(&ObjectRef([1; 32]), Scope::CHANGES, 0));

        assert_eq!(

            Scope::parse("changes, refs").unwrap(),

            Scope::CHANGES | Scope::REFS

        );

        assert_eq!(Scope::parse("all").unwrap(), Scope::ALL);

        assert_eq!((Scope::CHANGES | Scope::SEAL).to_string(), "changes,seal");

        assert!(Scope::parse("push").is_err() && Scope::parse("").is_err());

        // An identity written before scopes existed lists bare KeyIds.

        let mut v = id.to_value();

        if let Value::Map(m) = &mut v {

            m.insert(8, Value::Array(vec![Value::Bytes(host.0.to_vec())]));

        }

        let old = Identity::decode(&cbor::encode(&v)).unwrap();

        assert_eq!(old.delegates, vec![Delegate::full(host)]);

        assert!(old.delegates_to(&host, Scope::ALL, u64::MAX));

            user.delegate_add(hub_id.clone(), Scope::CHANGES | Scope::REFS, None)

                .unwrap();

    }

    /// Agent doc §2: an agent's key signs changes for its owner and nothing

    /// more. Its reference attestation is refused even though its owner's

    /// would pass, and a seal it makes authenticates nothing.

    #[test]

    fn a_changes_only_delegate_signs_changes_but_cannot_seal_or_move_a_reference() {

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

        let (host, mut user, _, _, _) = setup(dir.path(), true, false);

        let agent_sk = SecretKey::generate();

        let agent_id = agent_sk.identity("aider on a laptop", "agent@example", 1);

        let agent = agent_id.hash();

        user.delegate_add(agent_id.clone(), Scope::CHANGES, None)

            .unwrap();

        // The successor identity reaches the host with the rotated policy.

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

        let author = user.config.author_key.unwrap();

        let ids = vec![agent_id.clone(), user.identity(&author).unwrap()];

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

        let change = host

            .build_change(

                &heads,

                &[FileEdit {

                    path: "a.txt".into(),

                    content: Some(b"by the agent\n".to_vec()),

                }],

                "Agent edit",

                author,

            )

            .unwrap();

        let hash = change.hash();

        let sig = agent_sk.sign(Domain::Change, &agent, &hash);

        // Attested by the agent: refused, the reference stays.

        let update = host

            .host_ref_update("main", &[hash], Some((&agent, &agent_sk)))

            .unwrap();

        let report = host

            .apply_hosted(Some((change.clone(), vec![sig.clone()])), &ids, update)

            .unwrap();

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

        assert_eq!(host.bookmark_heads().unwrap(), heads);

        // Attested by the owner: the agent-signed change lands.

        let (owner, owner_sk) = user.secret_key().unwrap().unwrap();

        let update = host

            .host_ref_update("main", &[hash], Some((&owner, &owner_sk)))

            .unwrap();

        let report = host

            .apply_hosted(Some((change, vec![sig])), &ids, update)

            .unwrap();

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

        assert_eq!(host.bookmark_heads().unwrap(), vec![hash]);

        assert!(matches!(

            host.authenticate_change(&hash).unwrap(),

            SignatureStatus::Valid { key, sealed: false, .. } if key == agent

        ));

        // A seal by the agent is outside its scope.

        let change2 = host

            .build_change(

                &[hash],

                &[FileEdit {

                    path: "a.txt".into(),

                    content: Some(b"sealed by the agent\n".to_vec()),

                }],

                "Sealed",

                author,

            )

            .unwrap();

        let h2 = host.store().put_change(&change2).unwrap();

        let seal = host

            .store()

            .put_attest(&Attest::seal(host.id().unwrap(), vec![h2]))

            .unwrap();

        host.store()

            .put_signature(&seal, &agent_sk.sign(Domain::Attest, &agent, &seal))

            .unwrap();

        host.store().index_seal(&h2, &seal).unwrap();

        assert!(matches!(

            host.authenticate_change(&h2).unwrap(),

            SignatureStatus::Invalid(e) if e.contains("may not seal")

        ));

    }

    /// A delegation past its expiry authenticates nothing made after it,

    /// and the delegator may revoke the key; a stranger's key, they may not.

    #[test]

    fn an_expired_delegation_is_refused_and_the_delegator_may_revoke() {

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

        let (_, mut user, _, _, _) = setup(dir.path(), false, false);

        let agent_sk = SecretKey::generate();

        let agent_id = agent_sk.identity("agent", "agent@example", 1);

        let agent = agent_id.hash();

        let yesterday = Hlc::now().wall_ms - 24 * 3600 * 1000;

        user.delegate_add(agent_id, Scope::CHANGES, Some(yesterday))

            .unwrap();

        user.config.set("core.sign", "seal").unwrap();

        user.save_config().unwrap();

        write(&dir.path().join("work"), "a.txt", b"later\n");

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

        let h = user.commit("after the delegation ended", &[]).unwrap();

        user.store()

            .put_signature(&h, &agent_sk.sign(Domain::Change, &agent, &h))

            .unwrap();

        let status = user.verify_change(&h).unwrap();

        assert!(

            matches!(&status, SignatureStatus::Invalid(e) if e.contains("expired")),

            "{status:?}"

        );

        // No policy here, so the user is no root: only delegation lets them revoke.

        let stranger = SecretKey::generate().identity("x", "x@example", 1).hash();

        assert!(user.revoke_identity(&stranger, "").is_err());

        assert!(user.revoke_identity(&agent, "session over").is_ok());

        assert!(user.is_revoked(&agent).unwrap());

        let r = user.delegate_remove(&agent).unwrap();

        assert!(user.identity(&r.new).unwrap().delegates.is_empty());

    /// Let `delegate` act on this identity's behalf within `scope` until

    /// `expires` (spec §14.2). Delegates are part of the identity object,

    /// so this re-issues it with the same keys.

    pub fn delegate_add(

        &mut self,

        delegate: Identity,

        scope: Scope,

        expires: Option<u64>,

    ) -> Result<Rotation> {

        if scope.is_empty() {

            return fail("a delegate needs at least one scope: changes, refs or seal");

        }

        if cur.delegate(&dk).is_some() {

            return fail(format!(

                "{} is already a delegate; remove it first to change its scope or expiry",

                dk.short(12)

            ));

        delegates.push(Delegate {

            key: dk,

            scope,

            expires,

        });

            &format!("oxy identity delegate add {} --scope {scope}", dk.short(12)),

        if cur.delegate(delegate).is_none() {

            .filter(|d| d.key != *delegate)

    /// Revoke `key` (your own, one you delegated to, or any key when you

    /// hold a policy root): record a signed `revoke` attestation and a

    /// local marker, and drop the key from the policy where it has one.

    /// Revoking a delegate does not re-issue the identity; `delegate_remove`

    /// does that, and the CLI does both.

        let is_delegate = self.identity(&own)?.delegate(key).is_some();

        if *key != own && !is_root && !is_delegate {

            return fail("only the key's holder, the identity that delegated to it, or a policy root can revoke it");

        // then authorises that key for the reference as usual. A delegate

        // acts within its scope, signing changes or sealing them, and only

        // until its delegation expires (§14.2).

        if !change.author.is_zero() && sig.key != change.author {

            let needed = match domain {

                Domain::Change => Scope::CHANGES,

                _ => Scope::SEAL,

            };

            let delegation = self

                .ok()

                .and_then(|a| a.delegate(&sig.key).copied());

            match delegation {

                None => {

                    return Err(format!(

                        "key {} is neither the author nor a delegate",

                        sig.key.short(12)

                    ))

                }

                Some(d) if !d.scope.has(needed) => {

                    return Err(format!(

                        "key {} is a delegate for {} only and may not {}",

                        sig.key.short(12),

                        d.scope,

                        if needed == Scope::SEAL {

                            "seal"

                        } else {

                            "sign changes"

                        }

                    ))

                }

                Some(d) if !d.allows(needed, change.hlc.wall_ms) => {

                    return Err(format!(

                        "key {}'s delegation had expired when the change was made",

                        sig.key.short(12)

                    ))

                }

                Some(_) => {}

            }

use crate::identity::{

    verify as verify_signature, Delegate, Domain, Identity, Scope, SecretKey, Signature,

};

    /// named the delegate with the `refs` scope, still in force at `at_ms`

    /// (the attestation's wall time), and the policy names the identity.

    /// Revoked keys authorize nothing either way.

        at_ms: u64,

                    .is_some_and(|id| id.delegates_to(signer, Scope::REFS, at_ms))

            if !p.authorizes(&signer, &u.name)

                && !self.delegate_authorized(p, &signer, &u.name, sa.attest.hlc.wall_ms)

            {

            if !p.authorizes(&signer, &u.name)

                && !self.delegate_authorized(p, &signer, &u.name, sa.attest.hlc.wall_ms)

            {

                if !p.authorizes(&signer, &r.name)

                    && !self.delegate_authorized(p, &signer, &r.name, sa.attest.hlc.wall_ms)

                    && !self.delegate_authorized(p, &sig.key, &reference, sa.attest.hlc.wall_ms)

    let r = a.delegate_add(id_b.clone(), Scope::ALL, None).unwrap();

        a.identity(&key_a2).unwrap().delegates,

        vec![Delegate::full(key_b)]

    );

    assert_eq!(

    );

    assert!(

        a.delegate_add(id_b.clone(), Scope::ALL, None).is_err(),

        "already a delegate"

**Scoped delegation (§14.2, implemented 2026-10-04).** Before it, a

delegate moved references as far as its delegator may (§14.5). That is

right for a hub signing browser edits, and wrong for an agent. `delegates`

is a list of entries:

- A bare KeyId in an older identity means every scope.

**Revocation by the delegator (implemented 2026-10-04).** Before it,

only the revoked key itself or a policy root key could sign `revoke`. An agent's key may be lost on a

| Scoped, expiring delegates (done 2026-10-04) | §14.2 identity object, §14.4, §14.5 policy |

| Revocation by the delegator (done 2026-10-04) | §14.2 |

oxy identity delegate add agent.identity --expires 8h       # sign changes for me today

oxy identity delegate add ci.identity --scope changes,refs  # sign and push for me

oxy identity revoke 3f2a… --reason "agent host compromised" # a key you delegated to

  delegates  [8]: [Delegate]          // keys allowed to act on this identity's behalf

Delegate {

  key     [0]: KeyId

  scope   [1]: ["changes" | "refs" | "seal"]   // what it may do, in that order

  expires [2]: u64 | null                       // wall ms; null for as long as it is listed

}

The two public keys live in one object, so a `KeyId` names the pair. `delegates` lists keys that may act for this identity, each within a **scope**: `changes` lets the key sign changes whose `author` is this identity, `seal` lets it seal them, and `refs` lets it attest references and tags as this identity would (§14.5). A proxy acting for a Thin client (§22) or a host that commits browser edits for a user gets `changes,refs`; an AI agent gets `changes` alone, so its signature authenticates the changes it makes but it can never move a reference, whatever its owner may do. A delegation with `expires` authenticates nothing whose `hlc.wall_ms` is later than that, so an agent can be let in for a session without changing the owner's own expiry. Delegation is one level deep and is not transitive. A bare `KeyId` in `delegates`, as identities carried before scopes existed, means every scope with no expiry. Rotation is a new identity with `previous` set, plus an attestation of kind `rotate` signed by the previous key. Revocation is an attestation of kind `revoke` signed by the revoked key, by the identity that delegated to it, or by a policy root key (§14.5); the delegator's revocation marks the changes the key already signed as valid but revoked, and the delegator then re-issues their identity without it.

**Verification.** A sealed change `C` is authenticated iff a seal `S` exists such that `hash(C) ∈ S.body.hashes`, `S` carries a valid signature from key `K`, and `K` equals `C.author` or is listed in `C.author`'s identity as a delegate with the `seal` scope, not expired at `C.hlc.wall_ms` (§14.2). The same author-or-delegate rule applies to individual change signatures, with the `changes` scope. This rule is what stops a collaborator from sealing a change whose `author` field names someone else (§3.1). A change whose `author` is the zero KeyId names nobody (history imported from Git, §21, or made before an identity existed), so a seal from any key authenticates it: the sealer **adopts** it, and policy authorizes the sealer for the reference as usual. A push seals the pusher's own unauthenticated changes and adopts anonymous ones in the same seal. A seal's signer must additionally be authorized by policy for the reference being pushed.

- A reference attestation's signer is authorized by a rule if the rule lists it, or lists an identity whose `delegates` name it with the `refs` scope, not expired at the attestation's `hlc.wall_ms` (§14.2). Delegation is the identity's own signed statement and the policy names that identity, so a delegate with `refs` moves references exactly as far as its delegator may; revoking either key, or the delegation expiring, ends it. Hosts use this to land and to commit browser edits on a user's behalf with their own key. A delegate without `refs` (an agent) is never authorized for a reference or tag, even when its delegator is.

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

/// `30m`, `8h`, `7d`, or a bare number of days, as a wall time from now.

fn expiry_from_duration(s: &str) -> Result<u64> {

    let s = s.trim();

    let (n, unit) = match s.char_indices().find(|(_, c)| !c.is_ascii_digit()) {

        Some((i, _)) => (&s[..i], &s[i..]),

        None => (s, "d"),

    };

    let n: u64 = n.parse().map_err(|_| {

        anyhow::anyhow!("--expires takes 30m, 8h, 7d or a number of days, not {s:?}")

    })?;

    let ms = match unit {

        "m" => 60_000,

        "h" => 3_600_000,

        "d" => DAY_MS,

        _ => anyhow::bail!("--expires takes 30m, 8h, 7d or a number of days, not {s:?}"),

    };

    if n == 0 {

        anyhow::bail!("--expires needs a length of time; leave it out for no expiry");

    }

    Ok(Hlc::now().wall_ms + n * ms)

}

/// One line per delegate: key, scope, expiry.

fn delegate_lines(delegates: &[Delegate]) -> String {

    delegates

        .iter()

        .map(|d| {

            format!(

                "{} ({}{})",

                d.key.short(12),

                d.scope,

                d.expires

                    .map(|e| format!(", until {}", when(e)))

                    .unwrap_or_default()

            )

        })

        .collect::<Vec<_>>()

        .join(" ")

}

            candidates.extend(id.delegates.iter().map(|d| d.key));

            ui::kv("delegates", delegate_lines(&r.identity.delegates))

        println!("{}", ui::kv("delegates", delegate_lines(&id.delegates)));

    // A revoked delegate comes off the identity too, so the successor no

    // longer names it (spec §14.2).

    let own = repo.config.author_key;

    let delegated = own.is_some_and(|o| {

        repo.identity(&o)

            .is_ok_and(|id| id.delegate(&key).is_some())

    });

    if delegated {

        let mut repo = repo;

        let r = repo.delegate_remove(&key)?;

        report_rotation(&r, "Undelegated")?;

        return Ok(0);

    }

pub fn delegate_add(identity_file: &Path, scope: &str, expires: Option<&str>) -> Result<i32> {

    let scope = Scope::parse(scope).map_err(|e| anyhow::anyhow!("{e}"))?;

    let expires = expires.map(expiry_from_duration).transpose()?;

    let r = repo.delegate_add(id, scope, expires)?;

    if !scope.has(Scope::REFS) {

        println!(

            "  {} {}",

            ui::note(),

            ui::dim("it may not move references: a push or tag it attests is refused")

        );

    }

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

            .identity(&d.key)

        let until = match d.expires {

            Some(e) if now > e => ui::err(format!("expired {}", ui::ago(e))),

            Some(e) => ui::dim(format!("until {}", when(e))),

            None => String::new(),

        };

            "  {} {}  {}  {} {}",

            ui::hash(d.key.short(12)),

            ui::author(who),

            ui::dim(d.scope.to_string()),

            until

        /// What it may do for you: changes, refs, seal (comma-separated) or all.

        /// An agent gets `changes`; a host that lands for you needs `changes,refs`

        #[arg(long, default_value = "changes")]

        scope: String,

        /// How long for: 30m, 8h, 7d, or a number of days (default: until removed)

        #[arg(long)]

        expires: Option<String>,

                DelegateCmd::Add {

                    identity_file,

                    scope,

                    expires,

                } => identity::delegate_add(&identity_file, &scope, expires.as_deref()),