@inrupt/solid-client / acl/acl

Module: acl/acl

Type aliases

Access

Ƭ Access: Object

An object with the boolean properties read, append, write and control, representing the respective Access Modes defined by the Web Access Control specification.

Since that specification is not finalised yet, this interface is still experimental.

Type declaration

Name

Type

append

boolean

control

boolean

read

boolean

write

boolean


AclDataset

Ƭ AclDataset: SolidDataset & WithResourceInfo & { internal_accessTo: UrlString }

A SolidDataset containing Access Control rules for another SolidDataset.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.


WithAccessibleAcl

Ƭ WithAccessibleAcl<ResourceExt>: ResourceExt & { internal_resourceInfo: { aclUrl: Exclude<WithServerResourceInfo["internal_resourceInfo"]["aclUrl"], undefined> } }

If this type applies to a Resource, its Access Control List, if it exists, is accessible to the currently authenticated user.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.

Type parameters

Name

Type

ResourceExt

extends WithServerResourceInfoWithServerResourceInfo


WithFallbackAcl

Ƭ WithFallbackAcl<ResourceExt>: ResourceExt & { internal_acl: { fallbackAcl: Exclude<WithAcl["internal_acl"]["fallbackAcl"], null> } }

If this type applies to a Resource, the Access Control List that applies to its nearest Container with an ACL is accessible to the currently authenticated user.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.

Type parameters

Name

Type

ResourceExt

extends WithAcl``WithAcl


WithResourceAcl

Ƭ WithResourceAcl<ResourceExt>: ResourceExt & { internal_acl: { resourceAcl: Exclude<WithAcl["internal_acl"]["resourceAcl"], null> } }

If this type applies to a Resource, an Access Control List that applies to it exists and is accessible to the currently authenticated user.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.

Type parameters

Name

Type

ResourceExt

extends WithAcl``WithAcl

Functions

createAcl

createAcl(targetResource): AclDataset

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Creates an empty resource ACL (Access Control List) for a given Resource.

Parameters

Name

Type

Description

targetResource

WithResourceInfo & WithAccessibleAcl

A Resource that does not have its own ACL yet (see hasResourceAcl).

Returns

AclDataset

An empty resource ACL for the given Resource.


createAclFromFallbackAcl

createAclFromFallbackAcl(resource): AclDataset

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Creates a resource ACL (Access Control List), initialised from the fallback ACL inherited from the given Resource’s Container (or another of its ancestor Containers). That is, the new ACL has the same rules/entries as the fallback ACL that currently applies to the Resource.

Parameters

Name

Type

Description

resource

WithFallbackAcl & WithServerResourceInfo & WithAccessibleAcl

A Resource without its own resource ACL (see hasResourceAcl) but with an accessible fallback ACL (see hasFallbackAcl).

Returns

AclDataset

A resource ACL initialised with the rules/entries from the Resource’s fallback ACL.


deleteAclFor

deleteAclFor<Resource>(resource, options?): Promise<Resource & { acl: { resourceAcl: null } }>

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Removes the resource ACL (Access Control List) from a Resource.

Once the resource ACL is removed from the Resource, the Resource relies on the fallback ACL inherited from the Resource’s parent Container (or another of its ancestor Containers).

Type parameters

Name

Type

Resource

extends WithResourceInfo & { } & { internal_resourceInfo: { aclUrl: string } }

Parameters

Name

Type

Description

resource

Resource

The Resource for which you want to delete the ACL.

options

Partial<typeof internal_defaultFetchOptions>

Optional parameter options.fetch: An alternative fetch function to make the HTTP request, compatible with the browser-native fetch API.

Returns

Promise<Resource & { acl: { resourceAcl: null } }>


getFallbackAcl

getFallbackAcl(resource): AclDataset

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Returns the fallback ACL (Access Control List) attached to a Resource.

If the Resource has a fallback ACL attached and is accessible by the user (see hasFallbackAcl), the function returns the fallback ACL. If the Resource does not hava a fallback ACL attached or is inaccessible by the user, the function returns null.

Parameters

Name

Type

Description

resource

WithFallbackAcl

A Resource with potentially a fallback ACL attached.

Returns

AclDataset

The fallback ACL if available or null if not.

Defined in

src/acl/acl.ts:265

getFallbackAcl(dataset): AclDataset | null

Parameters

Name

Type

dataset

WithAcl

Returns

AclDataset | null


getFileWithAcl

getFileWithAcl(input, options?): Promise<File & WithServerResourceInfo & WithAcl>

Note

This function is still experimental and subject to change, even in a non-major release.

Retrieves a file, its resource ACL (Access Control List) if available, and its fallback ACL from a URL and returns them as a blob.

If the user calling the function does not have access to the file’s resource ACL, hasAccessibleAcl on the returned blob returns false. If the user has access to the file’s resource ACL but the resource ACL does not exist, getResourceAcl on the returned blob returns null. If the fallback ACL is inaccessible by the user, getFallbackAcl on the returned blob returns null.

Tip

To retrieve the ACLs, the function results in multiple HTTP requests rather than a single request as mandated by the Solid spec. As such, prefer getFile instead if you do not need the ACL.

since 0.2.0

Parameters

Name

Type

Description

input

Url | UrlString

-

options

Partial<typeof internal_defaultFetchOptions>

Fetching options: a custom fetcher and/or headers.

Returns

Promise<File & WithServerResourceInfo & WithAcl>

A file and its ACLs, if available to the authenticated user, as a blob.


getResourceAcl

getResourceAcl(resource): AclDataset

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Returns the resource ACL (Access Control List) attached to a Resource.

If the Resource has its resource ACL attached and is accessible by the user (see hasResourceAcl), the function returns the resource ACL. If the Resource does not have a resource ACL attached or is inaccessible by the user, the function returns null.

Parameters

Name

Type

Description

resource

WithAcl & WithServerResourceInfo & WithResourceAcl

A Resource with potentially an ACL attached.

Returns

AclDataset

The resource ACL if available and null if not.

Defined in

src/acl/acl.ts:207

getResourceAcl(resource): AclDataset | null

Parameters

Name

Type

resource

WithAcl & WithServerResourceInfo

Returns

AclDataset | null


getResourceInfoWithAcl

getResourceInfoWithAcl(url, options?): Promise<WithServerResourceInfo & WithAcl>

Experimental: fetch a Resource’s metadata and its associated Access Control List.

This is an experimental function that fetches both a Resource’s metadata, the linked ACL Resource (if available), and the ACL that applies to it if the linked ACL Resource is not available (if accessible). This can result in many HTTP requests being executed, in lieu of the Solid spec mandating servers to provide this info in a single request.

If the Resource’s linked ACL Resource could not be fetched (because it does not exist, or because the authenticated user does not have access to it), acl.resourceAcl will be null. If the applicable Container’s ACL is not accessible to the authenticated user, acl.fallbackAcl will be null.

Parameters

Name

Type

Description

url

UrlString

URL of the SolidDataset to fetch.

options

Partial<typeof internal_defaultFetchOptions>

Optional parameter options.fetch: An alternative fetch function to make the HTTP request, compatible with the browser-native fetch API.

Returns

Promise<WithServerResourceInfo & WithAcl>

A Resource’s metadata and the ACLs that apply to the Resource, if available to the authenticated user.


getSolidDatasetWithAcl

getSolidDatasetWithAcl(url, options?): Promise<SolidDataset & WithServerResourceInfo & WithAcl>

Experimental: fetch a SolidDataset and its associated Access Control List.

This is an experimental function that fetches both a Resource, the linked ACL Resource (if available), and the ACL that applies to it if the linked ACL Resource is not available. This can result in many HTTP requests being executed, in lieu of the Solid spec mandating servers to provide this info in a single request. Therefore, and because this function is still experimental, prefer getSolidDataset instead.

If the Resource does not advertise the ACL Resource (because the authenticated user does not have access to it), the acl property in the returned value will be null. acl.resourceAcl will be undefined if the Resource’s linked ACL Resource could not be fetched (because it does not exist), and acl.fallbackAcl will be null if the applicable Container’s ACL is not accessible to the authenticated user.

Parameters

Name

Type

Description

url

UrlString | Url

URL of the SolidDataset to fetch.

options

Partial<typeof internal_defaultFetchOptions>

Optional parameter options.fetch: An alternative fetch function to make the HTTP request, compatible with the browser-native fetch API.

Returns

Promise<SolidDataset & WithServerResourceInfo & WithAcl>

A SolidDataset and the ACLs that apply to it, if available to the authenticated user.


hasAccessibleAcl

hasAccessibleAcl<ResourceExt>(dataset): dataset is WithAccessibleAcl<ResourceExt>

Given a SolidDataset, verify whether its Access Control List is accessible to the current user.

This should generally only be true for SolidDatasets fetched by getSolidDatasetWithAcl.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.

Type parameters

Name

Type

ResourceExt

extends WithServerResourceInfo

Parameters

Name

Type

Description

dataset

ResourceExt

A SolidDataset.

Returns

dataset is WithAccessibleAcl<ResourceExt>

Whether the given dataset has a an ACL that is accessible to the current user.


hasAcl

hasAcl<T>(dataset): dataset is T & WithAcl

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Verify whether a given SolidDataset was fetched together with its Access Control List.

Type parameters

Name

Type

T

extends object

Parameters

Name

Type

Description

dataset

T

A SolidDataset that may have its ACLs attached.

Returns

dataset is T & WithAcl

True if dataset was fetched together with its ACLs.

Defined in

src/acl/acl.ts:65


hasFallbackAcl

hasFallbackAcl<Resource>(resource): resource is Resource & WithAcl & object

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Verifies whether the given Resource has a fallback ACL (Access Control List) attached.

A fallback ACL for a Resource is inherited from the Resource’s parent Container (or another of its ancestor Containers) and applies if the Resource does not have its own resource ACL.

The hasFallbackAcl function checks that:

  • a given Resource has a fallback ACL attached, and

  • the user calling hasFallbackAcl has Control access to the Container from which the Resource inherits its ACL.

To retrieve a Resource with its ACLs, see getSolidDatasetWithAcl.

Type parameters

Name

Type

Resource

extends WithAcl

Parameters

Name

Type

Description

resource

Resource

A SolidDataset that might have a fallback ACL attached.

Returns

resource is Resource & WithAcl & object

true if the Resource has a fallback ACL attached that is accessible to the user.


hasResourceAcl

hasResourceAcl<Resource>(resource): resource is Resource & WithAcl & object & WithResourceInfo & object & object

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Verifies whether the given Resource has a resource ACL (Access Control List) attached.

The hasResourceAcl function checks that:

  • a given Resource has a resource ACL attached, and

  • the user calling hasResourceAcl has Control access to the Resource.

To retrieve a Resource with its ACLs, see getSolidDatasetWithAcl.

Type parameters

Name

Type

Resource

extends WithAcl & WithResourceInfo & { }

Parameters

Name

Type

Description

resource

Resource

A Resource that might have an ACL attached.

Returns

resource is Resource & WithAcl & object & WithResourceInfo & object & object

true if the Resource has a resource ACL attached that is accessible by the user.

Defined in

src/acl/acl.ts:86


saveAclFor

saveAclFor(resource, resourceAcl, options?): Promise<AclDataset & WithResourceInfo>

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Saves the resource ACL for a Resource.

Parameters

Name

Type

Description

resource

WithAccessibleAcl

The Resource to which the given resource ACL applies.

resourceAcl

SolidDataset

An AclDataset whose ACL Rules will apply to resource.

options

Partial<typeof internal_defaultFetchOptions>

Optional parameter options.fetch: An alternative fetch function to make the HTTP request, compatible with the browser-native fetch API.

Returns

Promise<AclDataset & WithResourceInfo>