Access Policies: Universal API#

Note

Starting in solid-client version 1.19, to use the universal access API, import the universalAccess module from @inrupt/solid-client.

Access control/authorization determines which actions an Agent can perform on a Resource. For instance, an agent may have Read Access to a Resource, but not Write Access. Different Solid Servers can support different access control mechanisms; e.g., Access Control Policies (ACP) or Web Access Control (WAC).

To help simplify the handling of different access control mechanisms, the solid-client library provides universal access control APIs that can be used with either Access Control Policies (ACP) or Web Access Control (WAC). That is, for Resources that are controlled by either mechanisms, you can use the universal access control APIs to manage access instead of the mechanism-specific APIs.

Mechanism-specific APIs

When possible, use the universal access control APIs. However, the universal access control APIs are only available for features/functionalities of ACP and WAC that can be generalized. To handle ACP-specific or WAC-specific situations that cannot be generalized, the solid-client library provides ACP-specific APIs and WAC-specific APIs. For situations that require ACP-specific or WAC-specific APIs, see Mechanism-Specific Access Control APIs.

Access Object#

Using the solid-client library’s access control APIs, you can retrieve or modify the access for a Resource. The solid-client library handles access as an object of the form:

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

Where a <boolean> value of:

true indicates the access mode has been granted.
false indicates the access mode has not been granted.

The following access modes are available:

Access Mode	Description
`read`	The ability to view the contents of a Resource.
`append`	The ability to add new data to a Resource.
`write`	The ability to add new data to a Resource, and to change or remove existing data.

Retrieve Access Data for a Resource#

The solid-client library provides the following universal access control APIs to retrieve the access for a Resource:

These functions attempt to fetch the specified Resource, parse its access data that has been explicitly set for the specified Agent or the Public, and return a Promise that either resolves to an access object, or null if it could not be read.

Note

Starting in solid-client version 1.19, to use the universal access function, import the universalAccess module from @inrupt/solid-client.
To retrieve a Resource’s access data using these functions, the user must have appropriate access to read the access control for that Resource.

If an access object is returned,

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

The returned access is the access granted directly to that Agent or directly to the Public. That is, the returned access does not include access that may be indirectly set. For example, an Agent has not been directly granted the write access to a Resource, but write access has been given to the Public. Then, even though the Agent, by being a member of the general Public, has write access to the Resource and can modify the Resource, getAgentAccess returns write access as false.
The returned access applies only to the specified Resource and not to the Resource’s children. For example, if the getAgentAccess function indicates that an agent has read access to the Resource https://example.com/container/, that does not mean the agent also has read access to https://example.com/container/child.

If null is returned,

Access data is inaccessible by the user. Reasons for the inaccessibility are varied and can include:
- Inadequate access to retrieve the access data for that Resource.
- The access is defined in a way that is incompatible with the access model used by these APIs.
It is recommended that you explicitly check for null to handle the failure in your application.

Get Public Access#

The function getPublicAccess returns access granted specifically to the general public; that is, to everyone and not to specific Agents. To use getPublicAccess, pass it the following parameters:

The URL of the Resource.
The options object that contains the fetch function from an authenticated session. See Authentication.

Example#

Tip

Starting in solid-client version 1.19, to use the universal access function, import the universalAccess module from @inrupt/solid-client.

// ... import statement for authentication, which includes the fetch function, is omitted for brevity.

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

// ... Login logic omitted for brevity.

// Fetch the access explicitly/directly set for the public.
// The returned access can be an object { read: <boolean>, append: <boolean>, ... }
// or null if the access data is inaccessible to the user.
universalAccess.getPublicAccess(
  "https://example.com/resource",   // Resource
  { fetch: fetch }                  // fetch function from authenticated session
).then((returnedAccess) => {
  if (returnedAccess === null) {
    console.log("Could not load access details for this Resource.");
  } else {
    console.log("Returned Public Access:: ", JSON.stringify(returnedAccess));
  }
});

Returned Access#

The function returns access granted specifically to the general public and not to specific Agents.

For example, consider a situation where:
- you grant read access for a Resource to the Public (see setPublicAccess), and
- you also grant write access to specific Agents for the Resource.
The function returns only read as true, even though specific Agents may have additional access to the Resource.
The returned access applies only to the specified Resource and not to the Resource’s children.

Get Agent’s Access for a Resource#

The function getAgentAccess returns the access that has been explicitly granted to the specified Agent for the Resource. To use getAgentAccess, pass it the following parameters:

The URL of the Resource.
The WebID of the Agent whose access you want to return.
The options object that contains the fetch function from an authenticated session. See Authentication.

Example#

Tip

Starting in solid-client version 1.19, to use the universal access function, import the universalAccess module from @inrupt/solid-client.

// ... import statement for authentication, which includes the fetch function, is omitted for brevity.

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

// ... Login logic omitted for brevity.

// Fetch the access explicitly/directly set for an agent.
// (i.e., omits access inherited through public membership).
// The returned access can be an object { read: <boolean>, append: <boolean>, ... } 
// or null if the access data is inaccessible to the user.
universalAccess.getAgentAccess(
  "https://example.com/resource",       // resource  
  "https://id.example.com/someWebId",   // agent
  { fetch: fetch }                      // fetch function from authenticated session
).then((agentAccess) => {
  logAccessInfo("https://id.example.com/someWebId", agentAccess, "https://example.com/resource");
});

function logAccessInfo(agent, agentAccess, resource) {
  console.log(`For resource::: ${resource}`);
  if (agentAccess === null) {
    console.log(`Could not load ${agent}'s access details.`);
  } else {
    console.log(`${agent}'s Access:: ${JSON.stringify(agentAccess)}`);
  }
}

Returned Access#

The function does not return access that has been indirectly granted to the Agent, such as access granted to the Public.

For example, consider a scenario where:
- you grant read access for a Resource to the Public (see setPublicAccess), and
- you set read access to false explicitly for a specific Agent (see setAgentAccess) for that Resource.
For this Agent, the function returns read as false. However, in the absence of any other access rules that may affect the Agent’s read access, the Agent can read the Resource since the Public access grants the read to the Agent.
The returned access applies only to the specified Resource and not to the Resource’s children.

Get All Agents’ Access for a Resource#

The function getAgentAccessAll returns the explicitly set access to the Resource for each Agent whose access to the Resource has been explicitly set.

To use getAgentAccessAll, pass it the following parameters:

The URL of the Resource.
The options object that contains the fetch function from an authenticated session. See Authentication.

Example#

Tip

Starting in solid-client version 1.19, to use the universal access function, import the universalAccess module from @inrupt/solid-client.

// ... import statement for authentication, which includes the fetch function, is omitted for brevity.

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

// ... Login logic omitted for brevity.

// Fetch the access for all agents whose access has been explicitly/directly set
// (i.e., omits access inherited through public membership).
// The returned access can be an object { read: <boolean>, append: <boolean>, ... } 
// or null if the access data is inaccessible to the user.
universalAccess.getAgentAccessAll(
  "https://example.com/resource", // resource
  { fetch: fetch }                // fetch function from authenticated session
).then((accessByAgent) => {
  // => accessByAgent is an object with Agent WebIDs as keys,
  //    and their associated access object {read: <boolean>, ... } as values.
  for (const [agent, agentAccess] of Object.entries(accessByAgent)) {
    logAccessInfo(agent, agentAccess, resource);
  }
});

function logAccessInfo(agent, agentAccess, resource) {
  console.log(`For resource::: ${resource}`);
  if (agentAccess === null) {
    console.log(`Could not load ${agent}'s access details.`);
  } else {
    console.log(`${agent}'s Access:: ${JSON.stringify(agentAccess)}`);
  }
}

Returned Access#

The function does not return access that has been indirectly granted to an Agent, such as access granted to the Public.

For example, consider a scenario where:
- you grant read access for a Resource to the Public (see setPublicAccess), and
- you set read access to false explicitly for a specific Agent (see setAgentAccess) for that Resource.
For this Agent, the function returns read as false. However, in the absence of any other access rules that may affect the Agent’s read access, the Agent can read the Resource since the Public access grants the read to the Agent.
The returned access applies only to the specified Resource and not to the Resource’s children.

Changing Access Data for a Resource#

The solid-client library provides the following universal access control APIs to modify the access for a Resource:

Note

Starting in solid-client version 1.19, to use the universal access function, import the universalAccess module from @inrupt/solid-client.
To retrieve a Resource’s access data using these functions, the user must have appropriate access to modify the access for that Resource.

These functions modify the access that is directly associated with an Agent or the general Public. An Agent can have additional access granted indirectly, such as through access granted to the Public.

Pass into the function the access object with the specific modes you want to set. Set these modes to

true to grant that mode.
false to revoke access for that mode. That is, using these functions to set a mode to false removes access granted directly to the given agent/public, but does not prevent that access from being granted via other indirect means.

Modes that are unspecified in the access object remain unchanged.

These functions attempt to fetch the specified Resource, parse its access data, apply the specified access changes (unspecified access modes remain unchanged), save the access data back to the Pod, and return a Promise that either resolves to the updated access data, or null if it could not be read or changed.

If an access object is returned,

The returned access applies only to the specified Resource and not to the Resource’s children. For example, if the updated access indicates that an agent has read access to the Resource https://example.com/container/, that does not mean the agent also has read access to https://example.com/container/child.

If null is returned,

Access data is inaccessible and/or unmodifiable by the user. Reasons for these are varied and can include:
- Inadequate access to retrieve or modify the access data for that Resource.
- The access is defined in a way that is incompatible with the access model used by these APIs.
It is recommended that you explicitly check for null to handle the failure in your app.

Change Public Access#

The function setPublicAccess sets access specifically for the general public; that is for everyone and not for specific Agents.

Setting an access mode to true grants that mode.
Setting an access mode to false revokes access for that mode for the Public. Agents may still be granted the access mode directly. For example, if you set read access to false for a Resource using setPublicAccess, and you also grant read access to specific Agents for the Resource, getPublicAccess returns read as false, even though specific Agents may have read access to the Resource and can read from the Resource.
Modes that are unspecified in the access object remain unchanged.

Tip

Starting in solid-client version 1.19, to use the universal access function, import the universalAccess module from @inrupt/solid-client.

// ... import statement for authentication, which includes the fetch function, is omitted for brevity.

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

// ... Login logic omitted for brevity.

// Set access for the general Public (i.e., everyone):
// - Grant Read access
// - Remove any previously granted Write access.
// - Leave the rest (append, controlRead and controlWrite) unchanged.
// The returned access can be an object { read: <boolean>, append: <boolean>, ... }
// or null if the access data is inaccessible to the user.
universalAccess.setPublicAccess(
  "https://example.com/resource",  // Resource
  { read: true, write: false },    // Access object
  { fetch: fetch }                 // fetch function from authenticated session
).then((newAccess) => {
  if (newAccess === null) {
    console.log("Could not load access details for this Resource.");
  } else {
    console.log("Returned Public Access:: ", JSON.stringify(newAccess));

  }
});

Note

The returned access applies only to the specified Resource and not to the Resource’s children.

Change Agent Access#

The function setAgentAccess sets access for a specific Agent. The function does not affect access that may have been granted to the Agent indirectly, such as access granted to the Public.

Setting an access mode to true grants that mode.
Setting an access mode to false revokes access for that mode. The Agent may still be granted the access mode indirectly through general Public access.
Modes that are unspecified in the access object remain unchanged.

Tip

Starting in solid-client version 1.19, to use the universal access function, import the universalAccess module from @inrupt/solid-client.

// ... import statement for authentication, which includes the fetch function, is omitted for brevity.

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

// ... Login logic omitted for brevity.

// Set access for an Agent:
// - Grant Read access
// - Remove any previously granted Write access.
// - Leave the rest (append, controlRead and controlWrite) unchanged.
// The returned access can be an object { read: <boolean>, append: <boolean>, ... }
// or null if the access data is inaccessible to the user.
universalAccess.setAgentAccess(
  "https://example.com/resource",         // Resource
  "https://id.example.com/someWebId",     // Agent
  { read: true, write: false, },          // Access object
  { fetch: fetch }                         // fetch function from authenticated session
).then((newAccess) => {
  logAccessInfo("https://id.example.com/someWebId", newAccess, "https://example.com/resource")
});

function logAccessInfo(agent, agentAccess, resource) {
  console.log(`For resource::: ${resource}`);
  if (agentAccess === null) {
    console.log(`Could not load ${agent}'s access details.`);
  } else {
    console.log(`${agent}'s Access:: ${JSON.stringify(agentAccess)}`);
  }
}

Note

The returned access applies only to the specified Resource and not to the Resource’s children.

Mechanism-Specific Access Control APIs#

In addition to the universal access control APIs, the solid-client library also provides APIs specific to Access Control Policies (ACP) and APIs specific to Web Access Control (WAC).

When possible, use the universal access control APIs. However, the universal access control APIs are only available for features/functionalities of WAC and ACP that can be generalized. To handle a WAC-specific or ACP-specific situations that cannot be generalized, use the mechanism-specific APIs, such as:

To handle error conditions that are specific to the access control mechanism. For example, if a WAC-controlled Resource does not have a reachable Fallback ACL, you may want to initialize a Resource-specific ACL anyway.
To use mechanism-specific functionality. For example, in ACP, you can deny (not just revoke/unset) access, specify a creator-matching rule, specify a client-application matching rule. These functionalities are specific to ACP and are not available in WAC.
To specify access that does not have a universal access API equivalent. For example, the universal access APIs only affect or refer to the access of the Resource itself and not its children, if the Resource is a Container.

Note

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.

For more information on mechanism-specific APIs, see: