# Capability Tokens

sequenceDiagram
participant Alice
participant Bob

Note over Alice,Bob: Alice and Bob somehow know each other
Alice->>Alice: create_cap_grant(secret, bob, "protected_function_name")
Alice-->>Bob: secret
Bob->>Bob: create_cap_claim(secret, alice, function_list)
Note over Alice,Bob: Now Bob can call the function in Alice's node
Bob->>Alice: protected_function_name(params)
Alice-->>Bob: result
Note over Alice,Bob: At any time Alice can revoke
Alice->>Alice: revoke_cap_grant(bob, "protected_function_name")
Bob->>Alice: protected_function_name(params)
Alice-->>Bob: UNAUTHORIZED!

If the CapAccess is transferable, the secret can be transfered to other agents and Alice wouldn't filter by agent.

## Data structures

/// The entry for the ZomeCall capability grant.
/// This data is committed to the callee's source chain as a private entry.
/// The remote calling agent must provide a secret and we source their pubkey from the active
/// network connection. This must match the strictness of the CapAccess.
pub struct CapabilityGrant {
    /// A string by which to later query for saved grants.
    /// This does not need to be unique within a source chain.
    pub tag: String,
    /// Specifies who may claim this capability, and by what means
    pub access: CapAccess,
    /// Set of functions to which this capability grants ZomeCall access
    pub functions: GrantedFunctions,
    // @todo the payloads to curry to the functions
    // pub curry_payloads: CurryPayloads,
}

/// Represents access requirements for capability grants.
enum CapAccess {
    /// No restriction: callable by anyone.
    Unrestricted,
    /// Callable by anyone who can provide the secret.
    Transferable {
        /// The secret.
        secret: CapSecret,
    },
    /// Callable by anyone in the list of assignees who possesses the secret.
    Assigned {
        /// The secret.
        secret: CapSecret,
        /// Agents who can use this grant.
        assignees: HashSet<AgentPubKey>,
    },
}

/// System entry to hold a capability token claim for use as a caller.
/// Stored by a claimant so they can remember what's necessary to exercise
/// this capability by sending the secret to the grantor.
 struct CapabilityClaim {
    /// A string by which to later query for saved claims.
    /// This does not need to be unique within a source chain.
    tag: String,
    /// AgentPubKey of agent who authored the corresponding CapGrant.
    grantor: AgentPubKey,
    /// The secret needed to exercise this capability.
    /// This is the only bit sent over the wire to attempt a remote call.
    /// Note that the grantor may have revoked the corresponding grant since we received the claim
    /// so claims are only ever a 'best effort' basis.
    secret: CapSecret,
}