Multi-key Agent Language: Support multiple keys per user account

[data-coasys]

Background

From the Flux conversation (2026-02-10) between Nico and HexaField discussing prioritization.

Problem

Currently the agent language supports a single key per user. For CalC compliance and better security, users need the ability to:

• Have multiple keys associated with their AD4M account
• Connect keys from different devices
• Manage key lifecycle (add/revoke)

Proposed Solution

Extend the agent language to support a user representation with potentially multiple keys.

"The easy part is to change the agent language to have a user representation with potentially multiple keys." - Nico

Related

• CalC compliance requirements (key revoking)
• Holochain membranes for agent expulsion when key is revoked
• Potential integration with Greencheck/proof of personhood systems

Priority

High - This is foundational infrastructure needed before other features.

---

Issue created by Data from Flux conversation analysis
depends on d9011e34-8219-4ba1-bdd1-7d104a25cd1f/91215135-9143-46eb-8f5d-b38504a40392#683

[HexaField]

Implementation Plan: Multi-Key Agent Language

Problem Statement

The current agent language maps 1 DID → 1 key → 1 device. The AgentExpressionData stored on the Holochain DHT contains a single did string, and expressions are signed with a single Ed25519 key from lair-keystore. The existing EntanglementProof mechanism links external keys to the DID but doesn't grant them signing authority within AD4M itself.

This blocks:

• Multi-device usage (phone + laptop sharing one identity)
• Key rotation (compromised key can't be revoked without losing identity)
• CalC compliance (requires key lifecycle management)
• Agent expulsion from Holochain membranes when a key is revoked

Current Architecture

Agent {
  did: string              // did:key:z6Mk... (single Ed25519 key)
  perspective: Perspective  // public profile links
  directMessageLanguage: string
}

Holochain zome (agent_store):

• create_agent_expression(AgentExpression) — stores DID → profile link
• get_agent_expression(Did) — retrieves latest profile by DID
• Single ProfileLink link type, get_latest_link returns most recent

EntanglementProof (existing):

• Bidirectional proof: DID signs device key, device key signs DID
• Stored locally via GraphQL mutations, not on DHT
• No authority delegation — purely attestation

Proposed Architecture

Phase 1: Agent Expression with Key Set

Extend the agent expression to include an authorised key set — a list of public keys that are all valid signers for this agent identity.

New data model:

// agent_store_integrity
#[derive(Clone, Debug, Deserialize, Serialize, SerializedBytes)]
pub struct AuthorisedKey {
    pub key: String,           // base58 Ed25519 public key
    pub name: String,          // human label ("MacBook", "Phone")
    pub added_at: DateTime<Utc>,
    pub added_by: String,      // key that authorised this addition
    pub proof: KeyAuthorisation, // signed by existing authorised key
}

#[derive(Clone, Debug, Deserialize, Serialize, SerializedBytes)]
pub struct KeyAuthorisation {
    pub authorising_key: String,  // which existing key signed this
    pub signature: String,         // signature over (new_key + did + timestamp)
}

#[derive(Clone, Debug, Deserialize, Serialize, SerializedBytes)]
pub struct KeyRevocation {
    pub revoked_key: String,
    pub revoked_at: DateTime<Utc>,
    pub revoked_by: String,
    pub signature: String,      // signature over (revoked_key + did + timestamp)
    pub reason: Option<String>,
}

#[derive(Clone, Debug, Deserialize, Serialize, SerializedBytes)]
pub struct AgentExpressionData {
    pub did: String,
    pub perspective: Option<Perspective>,
    pub direct_message_language: Option<String>,
    pub authorised_keys: Vec<AuthorisedKey>,    // NEW
    pub revoked_keys: Vec<KeyRevocation>,       // NEW
}

Rules:

• The DID's original key is always the first authorised key (root key)
• Any authorised key can add new keys (signs a KeyAuthorisation)
• Any authorised key can revoke other keys (signs a KeyRevocation)
• Root key revocation = identity death (intentional — "burn this identity")
• Revoked keys appear in revoked_keys and are removed from authorised_keys

Phase 2: Expression Signing with Any Authorised Key

Currently ExpressionProof contains { signature, key }. No changes needed to the proof format — the key field already identifies which key signed. Validation changes:

1. Resolver update: When validating an expression, resolve the author's DID → agent expression → authorised_keys. Accept the signature if proof.key is in the authorised set and not in revoked_keys at the expression's timestamp.
2. Client update: AgentClient gains signWithKey(keyId) to select which device key signs expressions.

Phase 3: Holochain Membrane Integration

When a key is revoked:

1. Agent expression updated on DHT with the key in revoked_keys
2. Neighbourhood membranes can query the agent expression to check key validity
3. If the revoked key was the one used to join a membrane, the agent's Holochain cell for that neighbourhood can be blocked

New zome function:

#[hdk_extern]
pub fn is_key_valid(input: KeyValidityCheck) -> ExternResult<bool> {
    // Resolve DID → latest agent expression
    // Check key is in authorised_keys and not in revoked_keys
}

This becomes a building block for membrane rules in p-diff-sync neighbourhoods.

Phase 4: Device Pairing Flow

User-facing flow for adding a new device:

1. Device A (existing, has authorised key): generates a pairing code (short-lived, contains DID + challenge nonce)
2. Device B (new): enters pairing code, generates new Ed25519 keypair, signs the challenge with new key
3. Device A: verifies challenge response, creates AuthorisedKey entry signed by its own key, publishes updated agent expression
4. Device B: can now sign expressions as the same agent DID

This can reuse and extend the existing EntanglementProof infrastructure — the agentEntanglementProofPreFlight mutation already handles the bidirectional signing dance.

GraphQL API Changes

# New mutations
mutation agentAddAuthorisedKey(key: String!, name: String!): Agent
mutation agentRevokeKey(key: String!, reason: String): Agent
mutation agentGeneratePairingCode: String!
mutation agentCompletePairing(code: String!): Agent

# New query
query agentAuthorisedKeys: [AuthorisedKey!]!
query agentRevokedKeys: [KeyRevocation!]!
query agentIsKeyValid(did: String!, key: String!): Boolean!

Migration

• Existing agents get a single entry in authorised_keys (their current DID key) on first interaction with the updated system
• No breaking changes to AgentExpressionData — new fields are additive (Vec defaults to empty)
• Old clients that don't understand authorised_keys continue to work (they just see the DID key as before)

Scope & Phasing

Phase	Deliverable	Depends on
1	Data model + zome updates + agent expression with key set	New release
2	Expression validation against key set	Phase 1
3	Membrane integration for key revocation	Phase 2, p-diff-sync updates
4	Device pairing UX (ad4m-connect + Flux)	Phase 1

Phases 1-2 are the core. Phase 3 connects to neighbourhood governance. Phase 4 is the user-facing payoff.

Open Questions

1. Key hierarchy vs flat set? Current proposal is flat (any key can add/revoke). Alternative: tree hierarchy where only parent keys can revoke children. Simpler = better for now?
2. DID method change? did:key encodes a single key in the DID itself. Multi-key might warrant did:ad4m or did:plc-style where the DID is stable and keys rotate underneath. This is a larger conversation.
3. Threshold signatures? Should critical operations (root key revocation, DID transfer) require M-of-N keys? Probably overkill for v1.
4. Holochain agent key vs AD4M signing key? Each Holochain cell has its own agent key. Multi-device means multiple HC agent keys mapping to one AD4M DID. The agent language already abstracts over this, but membrane proofs need thought.

cc @lucksus @data-bot-coasys