Manage Access to Data (ACP)

The following page provides an overview of Access Control Policies (ACP) as well as examples using @inrupt/solid-client library’s ACP-specific APIs.

Tip

The solid-client library also provides universal access control APIs that can be used with either Access Control Policy (ACP) or Web Access Control (WAC).

When possible, use the universal access control APIs instead of the ACP-specific APIs or WAC-specific APIs. For situations that require ACP-specific or WAC-specific APIs, see Mechanism-Specific Access Control APIs.

Note

This page is compatible with Inrupt’s Enterprise Solid Server (ESS) 2.0.

Access Control Policy (ACP)

With Access Control Policies (ACP), Pod owners can define Policies that determine access for their Pod’s resources.

• Each resource has an associated Access Control Resource (ACR).

• The ACR contains the Policies that determine authorization decisions for its associated resource.

• The Policies determine access for Pod resources. A policy statement consists of:

  • Matcher statements that specify conditions that must be satisfied for the Policy to take effect.

  • Access mode statements that specify which access modes are allowed and/or denied to the agent(s) satisfying the Matcher statements.

Access Control Resource (ACR)

Every Resource has an associated Access Control Resource (ACR). The ACR specifies the Policies that apply to the resource; these Policies determine the access to the resource.

If the resource is a Container (analogous to a folder in a file system), you can also specify default Member Policies in the Container’s ACR. A Container’s Default Member Policies apply to resources (contained in the Container) that do not have their own ACP policies explicitly defined.

If a resource has no Policies that apply to it (neither explicitly for the resource nor implicitly through default Member Policies), the resource is inaccessible. However, the Pod owner and other agents with access to modify the resource’s ACR can add new Policies to provide access to the resource.

For examples on adding policies to a resource’s ACR, see Examples.

Policies

Policies determine access for Pod resources.

Note

Policies are Things in Structured Data (RDF Resources) terminology and are identified by their URL, generally of the form {ACR URL}#{policy-name}. See also URL as Identifiers.

A policy consists of:

• Matcher statements that specify conditions that must be satisfied for the Policy to take effect.

• Access mode statements that specify which access modes are allowed and/or denied to the agent(s) satisfying the Matcher statements.

If

< allOf | anyOf > (Matcher(s)) evaluates to true, AND

< allOf | anyOf | noneOf > (Matcher(s)) evaluates to true, AND

…

Then

<allow (AccessMode(s)) | deny (AccessMode(s)) | allow (AccessMode(s)) AND deny (AccessMode(s)) >

Important

The noneOf() expression excludes matches from the allOf() and anyOf() expressions; i.e., you can use the noneOf() expression to refine the allOf() and anyOf() matches.

Because the noneOf() expression acts as a secondary/supplementary filter to the allOf() and anyOf() expressions, a Policy statement with only a noneOf() condition cannot be satisfied.

For examples on defining and applying policies to a resource, see Examples.

Matcher Statements

< allOf | anyOf > (Matcher(s)) evaluate to true, AND

< allOf | anyOf | noneOf > (Matcher(s)) evaluates to true, AND

…

Matchers

Matchers specify the conditions under which the Access Policy applies.

ESS supports the following types of Matchers:

Agent Matchers	To match agents by specific WebID(s). To match any authenticated agent. To match any and all authenticated and unauthenticated agents (i.e., the Public/everyone).
Client Matchers	To match client applications by specific client identifier. When verifying against a policy that specifies a Client Application Matcher, the user must be logged in. A Policy that specifies a Client Application Matcher but no Agent Matcher does not match any agent. To match any client application.
Verifiable Credentials Matchers	To match by Verifiable Credential(s) type; e.g., match VC type http://www.w3.org/ns/solid/vc#SolidAccessGrant. Can be used to enable the use of Access Grants. For details, see Access Grants.

Note

Matchers are Things in Structured Data (RDF Resources) terminology and are identified by their URL, generally of the form {ACR URL}#{matcher-name}. See also URL as Identifiers.

allOf, anyOf, noneOf Operators

A policy specifies its matchers in allOf(), anyOf(), and noneOf() operator expressions.

allOf(<matchers>)	Evaluates to true if all of its listed matchers evaluate to true.
anyOf(<matchers>)	Evaluates to true if any of its listed matchers evaluate to true.
noneOf(<matchers>)	Evaluates to true if none of its listed matchers evaluate to true. Important The noneOf() expression excludes matches from the allOf and anyOf expressions; i.e., you can use the noneOf expression to refine the allOf and anyOf matches. Because the noneOf() expression acts as a secondary/supplementary filter to the allOf and anyOf expressions, a Policy statement with only a noneOf(<matchers>) condition cannot be satisfied.

For examples on adding matchers and policies, see Examples.

ACP Access Modes

<allow (AccessMode(s)) | deny (AccessMode(s)) | allow (AccessMode(s)) AND deny (AccessMode(s)) >

Access Modes

Access Modes describe the permissions (i.e., access) that are allowed or denied for a resource.

The @inrupt/solid-client’s ACP APIs handle <Access Modes> specification as an object of the form:

{ read: <boolean>, append: <boolean>, write: <boolean> }

The available Access Modes are:

Access Mode	Description
Read	Permission to view/retrieve a resource. See also CRUD Operations and ACP Modes for access and CRUD operations on specific resource types.
Write	Permission to create a resource, update/replace the content of a resource, and delete a resource: Tip To create a resource, you must have Write access on both the resource and the resource’s container. To delete a resource, you must have Write access on both the resource and the resource’s container. See also CRUD Operations and ACP Modes for access and CRUD operations on specific resource types.
Append	Permission to add content to a resource: If a resource is a container (analogous to a folder in a file system), the Append permission on the resource allows agents to add new resources (container, RDF resource, non-RDF resource) to the container. If a resource is an RDF resource, the Append permission on resource allow agents to add statements to the resource or add properties or values to existing statements. See also CRUD Operations and ACP Modes for access and CRUD operations on specific resource types.

allow, deny Expressions

A policy statement specifies its access modes in allow(Access Modes) or deny(Access Modes) expressions:

Expression	Description
allow expression	Specifies the access modes to be granted.
deny expression	Specifies the access modes to be denied.

For examples on adding matchers and policies, see Examples.

Evaluating Access

An agent is granted an access mode for a resource if:

• The agent satisfies a Policy that allows the access mode for the resource, and

• The agent does not satisfy any Policy that denies that access mode for the resource.

If no “allow access” policy is satisfied for a resource, then that resource is inaccessible to the agent. That is, an unsatisfied “deny access” policy does not confer access.

Example 1:	If a resource only has a single policy that allows Read and Write for an agent, Then, the agent is granted Read and Write for the resource.
Example 2:	If a resource has: A policy that allows Read and Write for an agent, and A policy that denies Write for the same agent, Then, the agent is granted Read access for the resource.
Example3:	If a resource has defined only a single policy that denies Read and the policy is unsatisfied by an agent (i.e., the policy Matcher statement does not match the specific agent), Then, that agent still does not have Read access to that resource (since no allow policy for the resource is satisfied by the agent).

For examples on adding matchers and policies, see Examples.

CRUD Operations and ACP Modes

CreateReadUpdateDelete

To create a resource, the user requires either an Append or Write access.

Note

• The creation operation creates the resource and updates the content of the parent Container with the new resource’s metadata.

• Although, a Container is itself a SolidDataset, the table separates out the access for the Container and SolidDataset.

Target Resource	Description
SolidDataset	Either Append or Write access to the parent Container allows for the resource creation, depending on the library function used: saveSolidDatasetInContainer(): Either Append or Write access to the parent Container. saveSolidDatasetAt(): Write access to the parent Container.
Container	Either Append or Write access on the parent Container (under which the new Container is to be created) allows agents to create a new Container.
Non-RDF Resource	Either Append or Write access allows for the resource creation: saveFileInContainer(): Either Append and/or Write access to the parent Container. overwriteFile(): Write access to the parent Container and the to-be-created target file. Tip To create access policies for yet to be created files, you can specify the parent Container’s default member policy.

API and Solid Server Support

Inrupt’s solid-client library provides various ACP-specific functions to manage ACP policies.

Tip

The solid-client library also provides universal access control APIs that can be used with either Access Control Policy (ACP) or Web Access Control (WAC).

When possible, use the universal access control APIs instead of the ACP-specific APIs or WAC-specific APIs. For situations that require ACP-specific or WAC-specific APIs, see Mechanism-Specific Access Control APIs.

Using the mechanism-specific APIs, it is possible for you to define an access model that is incompatible with the universal access APIs and, therefore, can only be managed with the mechanism-specific APIs.

Inrupt’s Enterprise Solid Server (ESS) provides support for ACP.

For use with ESS 2.0, use @inrupt/solid-client library version 1.23.1 or greater. To access and use ACP-specific functions compatible with ESS 2.0, import acp_ess_2.

import { acp_ess_2 } from "@inrupt/solid-client";

ESS 2.0 includes changes to ACP in line with the Editor’s Draft of Access Control Policy. These changes have the following implications for the ACP-specific APIs:

• Matchers replace Rules. As such, various *Rule* APIs have been deprecated.

• ACP no longer supports Group matching (where Group is identified by its own URL). As such, various *Group* APIs have been deprecated.

• Access Policies and Matchers can only be defined in an ACR. In addition,

  • ACRs must directly link to a Resource,

  • Access Controls and member Access Controls must link to Policies, and

  • Policies must link to Access Modes and Matchers they use.

  As such, you can no longer save unused ACP elements. Concretely, it means that Policies and Matchers must all be defined in an ACR.

Examples

Note

This page is compatible with Inrupt’s Enterprise Solid Server (ESS) 2.0.

Create Policy to Match Agents and Clients

The following example sets up an app-friends-policy that allow Read and Write access to any Agent that satisfies the match-app-friends Matcher conditions; namely, Agents whose WebID matches one of the specified WebIDs and is using an application whose Client Identifier matches the specified Client IDs. When verifying against a policy that specifies a Client Application Matcher, the user must be logged in. A Policy that specifies a Client Application Matcher but no Agent Matcher does not match any agent.

Tip

When possible, use the universal access control APIs to manage access for a resource.

When not possible (such as to include client identifiers matchers), you can use the ACP-specific API to create Matchers and Policies for the resource. However, using the ACP- or WAC-specific API, it is possible to define an access model that is incompatible with the universal access APIs and, therefore, can only be managed with the mechanism-specific APIs.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2, asUrl } from "@inrupt/solid-client";


// ... Various logic, including login logic, omitted for brevity.
// ...


async function setupPolicyToMatchAgentsAndClients(resourceURL) {

  const agentsToMatch = [ "https://id.example.com/chattycarl", "https://id.example.com/busybee" ];
  const clientIDsToMatch = [ "https://myapp.example.net/appid" ];

  try {
    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,            // Resource whose ACR to set up
      { fetch: fetch }       // fetch from the authenticated session
    );

    // 2. Initialize a new Matcher.
    let appFriendsMatcher = acp_ess_2.createResourceMatcherFor(
      resourceWithAcr,
      "match-app-friends"
    );

    // 3. For the Matcher, specify the Agent(s) to match.
    agentsToMatch.forEach(agent => {
      appFriendsMatcher = acp_ess_2.addAgent(appFriendsMatcher, agent);
    })

    // 4. For the Matcher, specify the Client ID(s) to match.
    clientIDsToMatch.forEach(clientID => {
      appFriendsMatcher = acp_ess_2.addClient(appFriendsMatcher, clientID);
    })

    // 5. Add the Matcher definition to the Resource's ACR.
    resourceWithAcr = acp_ess_2.setResourceMatcher(
      resourceWithAcr,
      appFriendsMatcher
    );

    // 6. Create a Policy for the Matcher.
    let appFriendsPolicy = acp_ess_2.createResourcePolicyFor(
      resourceWithAcr,
      "app-friends-policy",
    );

    // 7. Add the appFriendsMatcher to the Policy as an allOf() expression.
    // Since using allOf() with a single Matcher, could also use anyOf() expression

    appFriendsPolicy = acp_ess_2.addAllOfMatcherUrl(
      appFriendsPolicy,
      appFriendsMatcher
    );

    // 8. Specify the access modes (e.g., allow Read and Write).
    appFriendsPolicy = acp_ess_2.setAllowModes(appFriendsPolicy,
      { read: true, write: true }
    );

    // 9. Apply the Policy to the resource.
    resourceWithAcr = acp_ess_2.addPolicyUrl(
      resourceWithAcr,
      asUrl(appFriendsPolicy)
    );

    // 10. Add the Policy definition to the resource's ACR. 
    resourceWithAcr = acp_ess_2.setResourcePolicy(
      resourceWithAcr,
      appFriendsPolicy
    );

    // 11. Save the modified ACR for the resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );

  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset with its ACR.

   let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
     resourceURL,            // Resource whose ACR to set up
     { fetch: fetch }       // fetch from the authenticated session
   );
   

   To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

2. acp_ess_2.createResourceMatcherFor to initialize the Matcher that will be used by the policy.

   let appFriendsMatcher = acp_ess_2.createResourceMatcherFor(
     resourceWithAcr,
     "match-app-friends"
   );
   

   When saved, the Matcher URL will be {ACR URL}#match-app-friends.

3. acp_ess_2.addAgent to specify the WebID of the agent(s) to match:

   agentsToMatch.forEach(agent => {
     appFriendsMatcher = acp_ess_2.addAgent(appFriendsMatcher, agent);
   })
   

4. acp_ess_2.addClient to specify the Client ID of the application(s) to match.

   clientIDsToMatch.forEach(clientID => {
     appFriendsMatcher = acp_ess_2.addClient(appFriendsMatcher, clientID);
   })
   

5. acp_ess_2.setResourceMatcher to store the new matcher definition to the ACR:

   resourceWithAcr = acp_ess_2.setResourceMatcher(
     resourceWithAcr,
     appFriendsMatcher
   );
   

6. acp_ess_2.createResourcePolicyFor to initialize the policy:

   let appFriendsPolicy = acp_ess_2.createResourcePolicyFor(
     resourceWithAcr,
     "app-friends-policy",
   );
   

   When saved, the policy URL will be {ACR URL}#app-friends-policy.

7. acp_ess_2.addAllOfMatcherUrl to add the matcher to the policy.

   // Since using allOf() with a single Matcher, could also use anyOf() expression
   
   appFriendsPolicy = acp_ess_2.addAllOfMatcherUrl(
     appFriendsPolicy,
     appFriendsMatcher
   );
   

8. acp_ess_2.setAllowModes to specify that the policy allows Read and Write modes:

   appFriendsPolicy = acp_ess_2.setAllowModes(appFriendsPolicy,
     { read: true, write: true }
   );
   

9. acp_ess_2.addPolicyUrl to apply the new policy to the resource:

   resourceWithAcr = acp_ess_2.addPolicyUrl(
     resourceWithAcr,
     asUrl(appFriendsPolicy)
   );
   

10. acp_ess_2.setResourcePolicy to store the new policy definition to the ACR:

    resourceWithAcr = acp_ess_2.setResourcePolicy(
      resourceWithAcr,
      appFriendsPolicy
    );
    

11. acp_ess_2.saveAcrFor to save the modified ACR.

    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );
    

Make a Resource Public: Create Public Policy for a Resource

The following example uses the ACP-specific APIs to set up a public-policy that allows Read access to the public (i.e., everyone) for a resource.

Tip

For the public-policy below, you can, instead, use the universal access control API setPublicAccess(resourceURL, {read: true}, { fetch: fetch }). The example below is shown only to illustrate the use of the acp_ess_2.setPublic API. When possible, use the universal access control APIs.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2 } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.
// ...

async function setupPublicReadPolicyForResource(resourceURL) {
  try {
    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,              // Resource for which to set up the policies
      { fetch: fetch }          // fetch from the authenticated session
    );

    // 2. Create a Matcher for the Resource.
    let resourcePublicMatcher = acp_ess_2.createResourceMatcherFor(
      resourceWithAcr,
      "match-public"  // Matcher URL will be {ACR URL}#match-public
    );

    // 3. Specify that the matcher matches the Public (i.e., everyone).
    resourcePublicMatcher = acp_ess_2.setPublic(resourcePublicMatcher);

    // 4. Add Matcher to the Resource's ACR.
    resourceWithAcr = acp_ess_2.setResourceMatcher(
      resourceWithAcr,
      resourcePublicMatcher,
    );

    // 5. Create the Policy for the Resource.
    let resourcePolicy = acp_ess_2.createResourcePolicyFor(
      resourceWithAcr,
      "public-policy",  // Policy URL will be {ACR URL}#public-policy
    );

    // 6. Add the Public Matcher to the Policy as an allOf() expression.
    resourcePolicy = acp_ess_2.addAllOfMatcherUrl(
      resourcePolicy,
      resourcePublicMatcher
    );

    // 7. Specify the access modes for the Policy.
    resourcePolicy = acp_ess_2.setAllowModes(
      resourcePolicy,
      { read: true, append: false, write: false },
    );

    // 8. Apply the Policy to the Resource.
    resourceWithAcr = acp_ess_2.addPolicyUrl(
       resourceWithAcr,
       asUrl(resourcePolicy)
     );

    // 9. Add the Policy definition to the Resource's ACR. 
    resourceWithAcr = acp_ess_2.setResourcePolicy(
       resourceWithAcr,
       resourcePolicy,
    );

    // 10. Save the ACR for the Resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );
  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

   let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
     resourceURL,              // Resource for which to set up the policies
     { fetch: fetch }          // fetch from the authenticated session
   );
   

   To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

2. acp_ess_2.createResourceMatcherFor to initialize the Matcher that will be used by the policy.

   let resourcePublicMatcher = acp_ess_2.createResourceMatcherFor(
     resourceWithAcr,
     "match-public"  // Matcher URL will be {ACR URL}#match-public
   );
   

   When saved, the Matcher URL will be {ACR URL}#match-public.

3. acp_ess_2.setPublic to specify that the matcher is a Public matcher; i.e., matches everyone.

   resourcePublicMatcher = acp_ess_2.setPublic(resourcePublicMatcher);
   

4. acp_ess_2.setResourceMatcher to store the matcher definition to the ACR:

   resourceWithAcr = acp_ess_2.setResourceMatcher(
     resourceWithAcr,
     resourcePublicMatcher,
   );
   

5. acp_ess_2.createResourcePolicyFor to initialize the policy for the Resource:

   let resourcePolicy = acp_ess_2.createResourcePolicyFor(
     resourceWithAcr,
     "public-policy",  // Policy URL will be {ACR URL}#public-policy
   );
   

   When saved, the policy URL will be {ACR URL}#public-policy.

6. acp_ess_2.addAllOfMatcherUrl to add the matcher to the policy.

   resourcePolicy = acp_ess_2.addAllOfMatcherUrl(
     resourcePolicy,
     resourcePublicMatcher
   );
   

7. acp_ess_2.setAllowModes to specify the access modes for the policy:

   resourcePolicy = acp_ess_2.setAllowModes(
     resourcePolicy,
     { read: true, append: false, write: false },
   );
   

8. acp_ess_2.addPolicyUrl to apply the new policy to the resource:

   resourceWithAcr = acp_ess_2.addPolicyUrl(
      resourceWithAcr,
      asUrl(resourcePolicy)
    );
   

9. acp_ess_2.setResourcePolicy to store the new policy definition to the ACR:

   resourceWithAcr = acp_ess_2.setResourcePolicy(
      resourceWithAcr,
      resourcePolicy,
   );
   

10. acp_ess_2.saveAcrFor to save the modified ACR.

    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );
    

View Policies and Matchers for a Resource

The following example uses the ACP-specific APIs to view the ACP policies for a resource.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2, solidDatasetAsTurtle } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.

async function viewResourceACR(resourceURL) {

  try {
    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    const resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,
      { fetch: fetch }            // fetch from the authenticated session
    );

    // 2a. Get the Access Control Resource (ACR)
    const myACR = await getSolidDataset(
      acp_ess_2.getLinkedAcrUrl(resourceWithAcr),
      { fetch: fetch }
    );
    
    // 2b. Output (formatted as Turtle) its policies and matchers details.
    console.log(solidDatasetAsTurtle(myACR));

    // 3a. Get all policies from the ACR to process policies.
    const myResourcePolicies = acp_ess_2.getResourcePolicyAll(resourceWithAcr);

    // Loop through each policy for processing.
    myResourcePolicies.forEach(policy => {
      //... 
    });

    // 3b. Get a specific policy from the ACR.
    const specificPolicy = acp_ess_2.getResourcePolicy(
      resourceWithAcr,
      "specify-the-name-of-policy-to-get"
    );

    // 4a. Get all matchers from the ACR to process matchers.
    const myResourceMatchers = acp_ess_2.getResourceMatcherAll(resourceWithAcr)

    // Loop through each matcher for processing.
    myResourceMatchers.forEach(matcher => {
      // ... 
    });

    // 4b. Get a specific matcher from the ACR.
    const specificMatcher = acp_ess_2.getResourceMatcher(
      resourceWithAcr,
      "specify-the-name-of-matcher-to-get"
    );


  } catch (error) {
      console.error(error.message);
  }
}

Details

In particular, the example uses:

1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

   const resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
     resourceURL,
     { fetch: fetch }            // fetch from the authenticated session
   );
   

   To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

2. getSolidDataset with getLinkedAcrUrl to retrieve the ACR.

   const myACR = await getSolidDataset(
     acp_ess_2.getLinkedAcrUrl(resourceWithAcr),
     { fetch: fetch }
   );
   

   Once you retrieve the ACR as a SolidDataset, you can use solidDatasetAsTurtle to format ACR as Turtle.

   console.log(solidDatasetAsTurtle(myACR));
   

3. acp_ess_2.getResourcePolicyAll to get the policies from the resource’s ACR.

   const myResourcePolicies = acp_ess_2.getResourcePolicyAll(resourceWithAcr);
   
   // Loop through each policy for processing.
   myResourcePolicies.forEach(policy => {
     //... 
   });
   

   To view a specific policy, you can use acp_ess_2.getResourcePolicy:

   const specificPolicy = acp_ess_2.getResourcePolicy(
     resourceWithAcr,
     "specify-the-name-of-policy-to-get"
   );
   

4. acp_ess_2.getResourceMatcherAll to get all matchers from the resource’s ACR.

   const myResourceMatchers = acp_ess_2.getResourceMatcherAll(resourceWithAcr)
   
   // Loop through each matcher for processing.
   myResourceMatchers.forEach(matcher => {
     // ... 
   });
   

   To view a specific matcher, you can use acp_ess_2.getResourceMatcher:

   const specificMatcher = acp_ess_2.getResourceMatcher(
     resourceWithAcr,
     "specify-the-name-of-matcher-to-get"
   );
   

Delete Existing Policy for a Resource

The following example deletes an existing Policy for a resource.

Tip

To view existing Policies for a resource, see View Policies and Matchers for a Resource.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2 } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.

async function deletePolicyForResource(resourceURL, policyName) {

  try {

    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,           // Resource whose policy you want to delete
      { fetch: fetch }       // fetch from the authenticated session
    );

    // 2. Remove the Policy definition from the ACR
    resourceWithAcr = acp_ess_2.removeResourcePolicy(resourceWithAcr, policyName);

    // 3. Save the ACR for the Resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );

  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

   let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
     resourceURL,           // Resource whose policy you want to delete
     { fetch: fetch }       // fetch from the authenticated session
   );
   

   To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

2. acp_ess_2.removeResourcePolicy to delete the Policy definition from the ACR:

   resourceWithAcr = acp_ess_2.removeResourcePolicy(resourceWithAcr, policyName);
   

   acp_ess_2.removeResourcePolicy can also accept the Policy URL or the Policy itself instead of the Policy name.

3. acp_ess_2.saveAcrFor to save the modified ACR.

   const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
     resourceWithAcr,
     { fetch: fetch }          // fetch from the authenticated session
   );
   

Modify Existing Matcher for a Resource

The following example continues from an earlier example. Specifically, the example modifies the match-app-friends created in Create Policy to Match Agents and Clients to remove one of the Agents from the match list.

Tip

To view existing Matchers for a resource, see View Policies and Matchers for a Resource.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2 } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.

async function removeAgentFromMatcher(resourceURL) {

  try {

    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
        resourceURL,           // Resource whose Matcher you want to modify
        { fetch: fetch }       // fetch from the authenticated session
    );

    // 2. Get the Matcher to modify.
    let matcherToModify = acp_ess_2.getResourceMatcher(
        resourceWithAcr,
        "match-app-friends" // Name of the Matcher created in an earlier example.
    );

    // 3. Modify the Matcher; e.g., remove an Agent from the Matcher.

    const agentToRemove="https://id.example.com/chattycarl";
    matcherToModify = acp_ess_2.removeAgent(matcherToModify, agentToRemove);

    // 4. Store the modified Matcher definition to the resource's ACR.
    resourceWithAcr = acp_ess_2.setResourceMatcher(
        resourceWithAcr,
        matcherToModify
    );

    // 5. Save the modified ACR for the resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
        resourceWithAcr,
        { fetch: fetch }          // fetch from the authenticated session
    );

  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

   let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
       resourceURL,           // Resource whose Matcher you want to modify
       { fetch: fetch }       // fetch from the authenticated session
   );
   

   To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

2. acp_ess_2.getResourceMatcher to get the Matcher from the resource’s ACR.

   let matcherToModify = acp_ess_2.getResourceMatcher(
       resourceWithAcr,
       "match-app-friends" // Name of the Matcher created in an earlier example.
   );
   

   The match-app-friends was created in an earlier example, Create Policy to Match Agents and Clients.

   Tip

   To view existing Matchers for a resource, see View Policies and Matchers for a Resource.

3. acp_ess_2.removeAgent to remove an Agent’s WebID from the list of the Matcher’s WebIDs to match.

   policyToModify = acp_ess_2.setAllowModes(policyToModify,
     { write: false }
   );
   

4. acp_ess_2.setResourceMatcher to update the Matcher definition in the ACR:

   resourceWithAcr = acp_ess_2.setResourcePolicy(
     resourceWithAcr,
     policyToModify
   );
   

5. acp_ess_2.saveAcrFor to save the modified ACR.

   const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
     resourceWithAcr,
     { fetch: fetch }          // fetch from the authenticated session
   );
   

Modify Existing Policy for a Resource

The following example continues from an earlier example. Specifically, the example modifies the app-friends-policy created in Create Policy to Match Agents and Clients.

Tip

To view existing Policies for a resource, see View Policies and Matchers for a Resource.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2 } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.

async function modifyAppFriendsPolicy(resourceURL) {

  try {

    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,           // Resource whose Policy you want to modify
      { fetch: fetch }       // fetch from the authenticated session
    );

    // 2. Get the Policy to modify. 
    let policyToModify = acp_ess_2.getResourcePolicy(
      resourceWithAcr,
      "app-friends-policy" // Name of the Policy created in an earlier example.
    );

    // 3. Change the Write access mode to false (from true). Other access modes remain unchanged.
    policyToModify = acp_ess_2.setAllowModes(policyToModify,
      { write: false }
    );

    // 4. Store the modified Policy definition to the resource's ACR. 
    resourceWithAcr = acp_ess_2.setResourcePolicy(
      resourceWithAcr,
      policyToModify
    );

    // 5. Save the modified ACR for the resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );

  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

   let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
     resourceURL,           // Resource whose Policy you want to modify
     { fetch: fetch }       // fetch from the authenticated session
   );
   

   To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

2. acp_ess_2.getResourcePolicy to get the Policy from the resource’s ACR. The app-friends-policy was created in an earlier example, Create Policy to Match Agents and Clients.

   let policyToModify = acp_ess_2.getResourcePolicy(
     resourceWithAcr,
     "app-friends-policy" // Name of the Policy created in an earlier example.
   );
   

   Tip

   To view existing Policies for a resource, see View Policies and Matchers for a Resource.

3. acp_ess_2.setAllowModes to update the Write access mode for the Policy. The other Access Modes for this Policy remain unchanged.

   policyToModify = acp_ess_2.setAllowModes(policyToModify,
     { write: false }
   );
   

   For additional Policy functions, see the API documentation.

4. acp_ess_2.setResourcePolicy to update the Policy definition in the ACR:

   resourceWithAcr = acp_ess_2.setResourcePolicy(
     resourceWithAcr,
     policyToModify
   );
   

5. acp_ess_2.saveAcrFor to save the modified ACR.

   const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
     resourceWithAcr,
     { fetch: fetch }          // fetch from the authenticated session
   );