AnyEvent-MCP

 view release on metacpan or  search on metacpan

lib/AnyEvent/MCP/Server/Permissions.pm  view on Meta::CPAN

=head1 NAME

AnyEvent::MCP::Server::Permissions - action authorization and sandbox grants

=head1 SYNOPSIS

   my $permissions = AnyEvent::MCP::Server::Permissions->new (
      name           => "example",
      actions        => { read => "Read file contents", write => "Modify files" },
      sandbox_grants => {
         "workdir-read"  => [],
         "workdir-write" => ["workdir-read"],
      },
      sandbox_grant_descriptions => {
         "workdir-read" => "Read the configured workdir",
      },
      sandbox_implementation => "bubblewrap",
   );

   my $grant = $req->require_permission ({
      tool           => $req->{tool},
      action         => "read",
      dimensions     => { subject => {
         label => "File", value => $path,
         choices => [{ label => "this file", match => $path }],
      } },
      sandbox_grants => ["workdir-read"],
      reason         => "read $path",
   });

=head1 DESCRIPTION

This module lets an MCP server check whether a tool operation is allowed
before doing the work. It applies ordered permission rules and asks the
user when a decision is needed. Users can allow or deny one operation,
or save a rule for future requests.

Attach a Permissions object to your server, then have each tool call
C<< $req->require_permission >> before starting its operation. The tool
describes what it wants to do and which worker privileges it needs. An
allowed request receives the granted sandbox privileges; a denied request
must not proceed.

By default, questions go to a local graphical or terminal helper. You can
instead configure the server to ask through an MCP client that supports
form elicitation. Saved rules can answer later requests without another
prompt; see L</RULE FILES>.

For HTTP, the transport must authenticate callers before dispatching MCP
requests. This module then authorizes operations for the accepted caller. The tool
must enforce the returned grants, for example by constructing a restricted
sandbox. The permission engine does not construct that sandbox or enforce
worker isolation itself.

=head2 The three separate questions

Authentication establishes who may call the MCP endpoint.
The permission engine answers whether a requested B<action> on a
B<subject> may proceed and which B<sandbox grants> the user approved.
The application's sandbox or other enforcement then determines what
the operation can actually do. None of the three substitutes for the others.

For example, a user may approve C<write> on a project but only with
C<workdir-write> authority. This does not authorize an arbitrary
command with network access, and an approval to write a buffer does not
imply approval to save it. Ask before side effects: permission prompts
can restart the tool callback. See
L<AnyEvent::MCP::Server::Toolset/Permission checks and retries>
and L<AnyEvent::MCP::Intro> for examples from actual servers.

=head1 PERMISSION REQUESTS

A request names an C<action> (a server-defined class of authority such as
C<inspect>, C<read>, C<write>, C<manage> or C<exec>), optional named
C<dimensions>, and the C<sandbox_grants> required by its worker. These are independent:
authorization to write does not imply authorization to read, although
sandbox-level C<workdir-write> may imply C<workdir-read>. C<tool> is optional
human-readable context identifying the actual MCP tool; rules do not match it.

An action may have a short human-readable description declared in C<actions>.
C<sandbox_grant_descriptions> similarly describes worker privileges, and
C<sandbox_implementation> identifies the enforcement environment (for example,
C<bubblewrap> or C<NONE - UNSANDBOXED>). These labels are explanatory, not
authorization identifiers, and the trusted server supplies them.

C<details> optionally maps plain display labels to Unicode text, for example
C<< { "View patch" => $diff } >>. These details are display-only and never
participate in rule matching or persistence. Supply complete text; the UI
chooses presentation, escaping and preview limits. Labels carry no UI
punctuation such as an ellipsis. The local YAD helper opens a text viewer;
terminal and native MCP forms include bounded previews in the prompt.

=head1 RULE FILES

Rules are evaluated in order, with the first match deciding. C<decision> is
C<allow>, C<deny> or C<ask>; omitted decisions are invalid. C<action> is the
server-defined action class, not the decision. A matcher beginning with C<^>
is interpreted as a Perl regular expression; otherwise it matches exactly.
Omitted C<match.NAME> fields do not restrict that dimension. For example:

   [rule]
   decision=allow
   action=read
   match.subject=^/home/example/documents/
   sandbox-grants=workdir-read

   [rule]
   decision=deny
   action=^

If any saved rule is invalid (including an obsolete pre-1.0 field), the
entire file is silently ignored and permissions are requested normally.
Reading does not modify the file; the next ordinary save replaces it,
discarding all old rules. Explicit saves do not validate rule semantics;
file I/O errors still fail normally.

An allow rule requires C<sandbox-grants>, which may be empty for actions



( run in 1.438 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )