RDF::ACL(3pm)

📦
version 0.104 · 5 versions
, in debian bookworm, ubuntu noble

💖 RDF::ACL 💖

okay bestie, welcome to the RDF::ACL(3pm) page — straight out of the User Contributed Perl Documentation section, and honestly? it's giving access control but make it ✨semantic✨.

🌸 NAME 🌸

RDF::ACL — access control lists for the semantic web 🕸️✨

🎀 SYNOPSIS 🎀

use RDF::ACL;

my $acl  = RDF::ACL->new('access.ttl');
my $auth = $acl->allow(
  webid => 'http://example.com/joe#me',
  item  => 'http://example.com/private/document',
  level => ['Read', 'Write'],
  );
$acl->save('turtle', 'access.ttl');

# later...

if ($acl->check('http://example.com/joe#me',
                'http://example.com/private/document',
                'Read'))
{
  print slurp("private/document");
}
else
{
  print "Denied";
}

# later...

foreach my $reason ($acl->why('http://example.com/joe#me',
                              'http://example.com/private/document',
                              'Read'))
{
  $acl->deny($reason) if defined $reason;
}
$acl->save('turtle', 'access.ttl');

🦋 DESCRIPTION 🦋

okay so first things first, the BIG disclaimer: this module does access control and it does NOT do authentication! 🚨 like, it will not check who you are, that is literally not its job. it just decides whether you're allowed to touch the thing. don't @ me.

🧚 Constructors

$acl->new($input, %args)

creates a brand new access control list based on the RDF data living in $input. and bestie, $input is flexible — it can be a serialised string of RDF, a file name, a URI, or literally any other input accepted by the parse function from RDF::TrineX::Functions. iconic.

and plot twist: you can call new() with no arguments at all to create a fresh, clean ACL containing zero authorisations. blank slate energy 💅

$acl->new_remote($endpoint)

creates a new access control list based on RDF data you reach via a remote SPARQL Protocol 1.0 endpoint. long distance relationship with your data, we love that 🫶

👑 Public Methods

$acl->check($webid, $item, $level, @data)

checks an agent's authorisation to access an item. the vibe check, but for permissions.

⚠️ this data is trusted blindly, so it should not include data that the user has themselves supplied. do not do it bestie, that's the whole point of access control 😭
  • if the ACL is remote, then this method throws an error if any additional data is provided. (a remote ACL simply cannot take local data into account. it's not personal.)
  • if $level is provided, this method returns a boolean.
  • if $level is undefined or omitted, this method returns a list of URIs which each represent a type of access that the user is authorised for. surprise bonus round 🎁

$acl->why($webid, $item, $level, @data)

investigates an agent's authorisation to access an item. detective mode 🕵️

arguments are as per check, however $level is required.

returns a list of authorisations that justify a user's access to the item at the given access level. these authorisations are equivalent to the $authid values that allow() hands you.

and in some cases (especially if the authorisation was created by hand, and not via allow()) an authorisation may not have an identifier. in those cases, the list will contain undef. yes, undef. it's fine. we cope. 💀

$acl->allow(%args)

adds an authorisation to the ACL. the ACL must be mutable — no edits on a locked vibe, sorry.

the method takes a hash of named arguments:

my $authid = $acl->allow(
  webid => 'http://example.com/joe#me',
  item  => 'http://example.com/private/document',
  level => ['Read', 'Write'],
  );

okay let's go through them one by one:

  • 'item' is the URI of the item to authorise access to. as an alternative, 'item_class' may be used to authorise access to an entire class of items (using classes in the RDFS/OWL sense of the word). if neither of these arguments is provided, then the method will throw an error. both may be provided. and either or both may be an arrayref, because an authorisation may authorise access to more than one thing. greedy but valid 💅
  • 'container' is an alternative to using 'item' or 'item_class'. it specifies the URI for a resource which in some way is a container for other resources. setting authorisations for a container lets you set a default authorisation for new items created within that container. (and you must use the created() method to notify the ACL about newly created items — don't forget, bestie, it won't just know.)
  • 'webid' is the WebID (URI) of the person or agent being granted access. as an alternative, 'agent_class' may be used to authorise access to an entire class of agents. if neither is provided, an agent_class of <http://xmlns.com/foaf/0.1/Agent> is assumed. both may be provided. either or both may be an arrayref, because an authorisation may authorise access by more than one agent. (and for consistency with 'item', 'agent' is supported as a synonym for 'webid'.) slay, consistency 🎀
  • 'level' is the access level being granted. same as with the check method, the shortcuts 'read', 'write', 'append' and 'control' may be used. an arrayref may be used. and if no level is specified, 'read' is assumed. default read, we love a low-stakes default 🍓

this authorisation is not automatically saved, so it's probably useful to call save() after adding authorisations. do it. please. 🙈

the method returns an identifier for the authorisation. you may need this identifier again if you ever need to deny() the authorisation, so hold onto it like it's a limited-edition friendship bracelet.

this method is aware of i_am()/who_am_i().

$acl->deny($authid)

completely removes all traces of an authorisation from the ACL. gone. deleted. no receipts.

the authorisation identifier can be found using why(), or you may have remembered it when you first allowed the access (main character memory ✨). in some cases (especially if the authorisation was created by hand, and not via allow()) an authorisation may not have an identifier. in those cases, you will have to be creative in figuring out how to deny access. good luck, you got this 🫶

returns the number of statements removed from the ACL's internal model as a result of the removal. (this will normally be at least 3.)

this authorisation is not automatically saved, so it's probably useful to call save() after removing authorisations.

this method is aware of i_am()/who_am_i().

$acl->created($item, $container)

finds all authorisations which are the default for new items within $container, and clones each of them for the newly created $item. copy-paste but make it permissions 🧬

returns a list of authorisation identifiers.

$acl->i_am($webid)

tells the ACL object to "act like" the agent with the given WebID. method acting, but for authorisation 💅

if the ACL object is acting like you, then methods that make changes to the ACL (e.g. allow() and deny()) will only work if you have 'Control' permission over the resources specified. rules are rules, bestie.

$webid can be null to restore the usual behaviour.

returns the previous WebID the ACL was acting like, as a URI object.

$acl->who_am_i

returns the WebID of the agent that the ACL is acting like (if any). existential crisis, but make it a return value 🌈

$acl->save($format, $filename)

serialises a local (not remote) ACL.

$format can be any format supported by the serialize function from RDF::TrineX::Functions.

if $filename is provided, this method writes to the file and returns the new file size in bytes.

if $filename is omitted, this method does not attempt to write to a file, and simply returns the string it would have written. ✍️

$acl->is_remote

returns true if the ACL is remote; false if local. quick little identity check 🔍

$acl->is_mutable

can this ACL be modified? 🤔

$acl->model

the graph model against which authorisation checks are made.

returned as an RDF::Trine::Model object.

$acl->endpoint

the endpoint URI for remote (non-local) ACL queries.

returned as a URI object.

💀 BUGS 💀

please report any bugs to <http://rt.cpan.org/>. do it for the girls (the girls are Perl developers) 🫶

👀 SEE ALSO 👀

👑 AUTHOR 👑

Toby Inkster <tobyink@cpan.org>. king behavior, we stan 💜

this software is copyright (c) 2010-2013 by Toby Inkster.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in freedom, and also free as in go off bestie ✨

🚨 DISCLAIMER OF WARRANTIES 🚨

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. 💀 no promises, no guarantees, you get what you get.

and that's the whole page, babe 🎀 this was RDF::ACL(3pm) from perl v5.34.0, dated 2022-06-17 — go forth, allow responsibly, and always remember to save() before you close the tab. mwah 🫶💖

📦 where this page comes from